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PREFACE 


This manual describes the BASIC-PLUS programming language. In- 
formation is organized for the benefit of the beginning programmer, as 
it allows the reader to gradually acquire increased programming capa- 
bilities. 


The BASIC-PLUS language is an extension of BASIC! as originally 
developed at Dartmouth College. The experienced BASIC programmer may 
find the appendices sufficient for his use. However, BASIC-PLUS offers 
many features not found in standard Dartmouth BASIC or any other ver~ 
sion of BASIC. 


While it is always good programming practice to use the % charac- 
ter to indicate integer format of variables, as described in Chapter 
6, the sample programs in this manual do not always follow this 
convention. For the sake of clarity in illustrating various program- 
ming concepts, the % character is omitted occasionally in these 
examples, but should be included in user programs to save storage 
Space as well as computing time. 


For information on all of the current manuals pertaining to 
RSTS/E operation, consult the RSTS/E Documentation Directory. 


‘BASIC is a registered trademark of the Trustees of Dartmouth College. 
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PART I 


RSTS/E AND THE BASIC-PLUS LANGUAGE 


_ This first Part describes the RSTS/E system, its hardware and. 
‘user features, and thé simplest level of the BASIC iaiguage.< BASIC 
as described here is essentially Dartmouth BASIC as originally: 
developed. Part II describes the extended capabilities of BASIC- 
PLUS. AS part of. ine introductory material, the reader will find - 
references os some of the extended Sapapiieress Part III describes 
the comprare Fande of BASIC-PLUS I/O, including Record £7 and 
information on particular I/O devices. 

As a Ganeusde: BASIC is easy to learn. BASIC-PLUS seoviaes 
many advanced features, which allow BASIC ‘to 6 a useful tool for 
the more experienced programmer. BASIC does not, nowavee; penels 
‘ize the beginning user. Almost. any. a ier can be solved with the 
iatensnee avantecie in Part I. The statements ed features in 


‘ = 


Parts II and III allow ‘the user ee write more efficient eode to” 


better use facning time and core space. 


CHAPTER 1 


AN INTRODUCTION TO RSTS-11 


In this manual, the RSTS-1l user need only be concerned with 
the writing and execution of correct programs in the BASIC-PLUS 


language. A description of the various RSTS-ili commands (NEW, OLD, 


LIST, RUN, etc.) can be found in the RSTS-11 System User's Guide. 


1.1 INTRODUCTION TO PROGRAMMING 
For the benefit of the new programmer approaching his first com- 


puting experience, there are four phases in programming a computer: 


a. writing the computer program, 
b. entering the program to the computing system, 
c. testing and debugging the program, and 


d. running the finished program. 


BASIC-PLUS is the language in which the user writes programs de- 
signed for the RSTS-1l system. Input of the completed program is 
generally performed from the terminal keyboard on RSTS-1l. 

A program can be input through various peripheral devices, such as 
the paper tape reader, magnetic tape, DECtape, or punched cards; how- 
ever, the initial creation of a BASIC program is usually performed 


on-line to the computer from the terminal keyboard. 


Ideally a program runs correctly as written; but in practice 
this is seldom the case. A program can contain simple typing mis- 
takes or complex logical errors. Typing and syntactical errors are 
detected as the program is typed at the keyboard and appropriate er- 
ror messages are printed. BASIC-PLUS also evaluates the entire pro- 
gram for commonly made errors and generates messages which explain 
the mistakes to the user. Program errors are corrected on-line from 


the terminal keyboard. 


The testing and debugging process is continued until the program 
appears to execute correctly. This is a good time to explain to the 


new user that a computer program only does what the programmer has 


written, The calculations performed by the computer are not necessar- 
ily those that will produce the correct results. In order to obtain 
correct results from a computer, the user must write a program which 
is not only free of detectable errors, but one which correctly ana- 


lyzes his problem. 


RSTS~11l provides keyboard commands which enable the user not 
only to create and execute his program but also to save the program 
within the system for later retrieval and execution or modification. 


This saving process is known as storing or filing the program. 


1.2 INTRODUCTION TO TIME-SHARING 
RSTS-1l is a time-sharing system, This means that when a user 
is working with RSTS, he has the illusion that he is the only user on 


the computer, 


Many users can be on-line to RSTS at one time because RSTS con- 
trols the scheduling of execution times. RSTS has one or more users 
in core at one time. Users are brought into core from disk, allowed 
to execute for a short time, and returned to disk. This process is 
called swapping. RSTS takes note of the state at which execution 


stops and is able to resume operation at that point. 
1 
Each user is allotted a block of core between 2K and 16K for stor- 


age of his particular program. This block is swapped between core 
and disk. If only one user job is active in the system at a given 
time, that job is allowed to execute without interruption until 


another program is ready. 


1.3 THE BASIC-PLUS PROGRAMMING LANGUAGE 

BASIC is one of the simplest of all programming languages because 
of the small number of powerful but easily understood statements and 
commands and its easy application to problem solving. The wide use 
of BASIC in scientific, business, and educational installations at- 
tests to its value and straightforward application. (For a bibliog- 
raphy of texts on BASIC and other elementary computing texts, see 
Appendix G.) 


BASIC is similar to many other programming languages in various 
respects but is especially suited for time-sharing because of its 
conversational nature. A conversational language is one which allows 
the user to communicate with the language processor by typing on the 
terminal keyboard. BASIC responds by printing on the terminal, 
providing for an interactive man/machine relationship. 


1 
The term "K" refers to 1924 (decimal) words of storage in a computer 
Hence, 2K=2848 words and 8K=8192 words. 


BASIC-PLUS contains both the elementary statements used to write 
simple programs and many new advanced programming features and state- 
ments to produce more complex and efficient programs. The key word 
here is efficient. As the user progresses and gains programming ex- 
perience, he will naturally find himself becoming more efficient and 
able to use the more sophisticated data manipulations. Almost any 
problem can be solved with the simple PASIC statements. Later in the 
user's programming experience, the advanced techniques can be added. 


1.4 CONVENTIONS USED IN THIS MANUAL 


Certain documentation conventions are used throughout this manual 
to clarify examples of BASIC syntax. Each BASIC statement is de- 
scribed at least once in general terms using the following conven- 
tions: 


a. Items in italic type (formula, variable, etc.) are supplied 
by the user according to rules explained in the text. Items 
in capital letters (LET, IF, THEN, etc.) must appear exactly 
as shown because they form the vocabulary of the BASIC language. 


b. The term line number used in examples indicates that any 
line number is valid. 


c. Angle brackets indicate essential elements of the statement 
or command being described. For example: 


line number{LET}<variable> = <expresston> 


d. Square brackets indicate a choice of one element among two 
or more possibilities. For example: 


THEN <statement> 
line number IF <expresston> | THEN <line number> 
GOTO <Lline number> 


e. Braces indicate an optional statement element or a choice 
of one element among two or more optional elements: 


THEN <statement> quale <statement> 
line number IF <expresston> THEN <line number>| ‘ ELSE <line number> 
GOTO <line number> 


} 


The use of some terms in this document may be unfamiliar to the 
new user. The following definitions and explanations are valid 


throughout this manual: 


a. BASIC prints on the teleprinter whereas the user types 
on the keyboard. 


1 


A statement is a single BASIC language instruction. Each 
BASIC program line is preceded by a line number and termi- 
nated by the RETURN key. A program line may contain a 
Single statement or several statements separated by colons 
(see Section 2.3.1). 


Commands cause BASIC to perform some operation im- 
mediately and are not preceded by a line number. 
A command is terminated by typing the RETURN key. 


A user program consists of a series of statements 
written by a person using the BASIC-PLUS language. 


The RSTS-11 terminal is in some cases an ASR-33 
Teletype!. However, RSTS-11 can accommodate a wide 
variety of other terminals such as a DECwriter or 
VT@5 display. The RSTS-11 user terminal is alter- 
natively referred to as terminal, teleprinter, or 
keyboard, depending upon whether a part or the 
whole device is indicated. The use of terminals 
and other peripheral devices is described in the 
RSTS-11 System User's Guide. 


The term BASIC is used interchangeably to indicate 
the BASIC language and the BASIC Interpreter (the 
system program which accepts and executes BASIC 
programs). 


Teletype is a registered trademark of the Teletype Corporation. 


CHAPTER 2 


FUNDAMENTALS OF PROGRAMMING IN BASIC-PLUS 


2.1 EXAMPLE BASIC PROGRAM 

The program in Figure 2.1 is an example of a user program writ- 
ten in the BASIC-PLUS language. It illustrates the syntax! and ele- 
ments of the language as well as standard formatting of statements 


and the appearance of terminal output. 


The user program (the lines numbered 10 through 200) may at this 
time mean little, although the remark in the first line (line 10) 
and the printed results (following the word RUNNH) show that the pro- 


gram computes interest payments. 


A user program is composed of lines of statements containing 
instructions to BASIC. Each line of the program begins with a line 
number that serves to identify that line as a statement and to in- 
dicate the order in which statements are to be evaluated for execution. 
Each statement starts with a word specifying the type of operation to 


be performed. 


2.2 LINE NUMBERS 


Each BASIC program line is preceded by a line number. Line 
numbers: 


a. indicate the order in which statements are normally 
evaluated; 
b. enable the normal order of evaluation to be changed; 


that is, the execution of the program can branch or 
loop through designated statements (this is explained 
further in the sections on the GOTO, GOSUB, and 
IF-THEN statements in Chapter 3); and 


c. enhance program debugging by permitting modification 
of any specified line without affecting any other 
portion of the program. 


Line numbers are in the range 1 to 32767. BASIC maintains pro- 
grams in line number sequence, rather than the order in which lines 
are entered to the system. It is good programming practice to num- 
ber lines in increments of 5 or 10 when first writing a program, to 
allow for insertion of forgotten or additional lines when debugging 
the program. 


‘The syntax of a language is the collection of rules governing the 
combination of language elements. 
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LISTNH 

1@ REMARK - THIS PROGRAM COMPUTES INTEREST PAYMENTS 

28 INPUT “INTEREST IN PERCENT" 3J 

38 LET J=J/188 

4@ INPUT "AMOUNT OF LOAN"; A 

58 INPUT "NUMBER OF YEARS"; N 

6@ INPUT "NUMBER OF PAYMENTS PER YEAR"; M 

78 LET N=NeM: IsJ/Ms: Brit] 

8@ LET R=AxI/(C1<1/BtN) 

92 PRINT 

168 PRINT “ AMOUNT PER PAYMENT 

118 PRINT “TOTAL INTEREST 

128 PRINT 

138 LET B=A 

146 PRINT “INTEREST APP TO PRIN BALANCE OF PRIN” 

158 LET L=B*¥Is: P=R-L: B=B-P 

168 PRINT INTCL¥1012+,.5)/1012, INTCP*1@T2+.5)/1812, 
INT(BHILST2+.5)/1872 

178 IF B>=R GOTO 158 

18@ PRINT INTC (B*I])*18T24+.5)/1892, INTC CR-B¥I)*18T2+.5)/18t2 

198 PRINT "LAST PAYMENT ="s INTC CB¥I+B) *1@T2+.5)/10t2 

208 END 


"3 INTCR*1612+.5)/18t2 
"s INTCCREN-A)*16T2+.5)/1072 


READY 


RUNNH 

INTEREST IN PERCENT? 7.5 
AMOUNT OF LOAN? 2586 

NUMBER OF YEARS? 2 

NUMBER OF PAYMENTS PER YEAR? 4 


AMOUNT PER PAYMENT = 339.44 


TOTAL INTEREST 215,51 
INTEREST APP TO PRIN BALANCE OF PRIN 
46.88 292.56 2207.44 

41.39 298.85 1989.39 

35.8 383.64 1685.75 

32.11 389.33 1296, 42 

24.31 315.13 981.28 

18.4 $21.84 668.24 

12,38 327.86 333.18 


6.25 333.19 
LAST PAYMENT = 339,43 


READY 


Figure 2-1 


Example BASIC Program 


When a program is executed (with the use of the RUN command), 
the BASIC processor evaluates the statements in the order of their 
line numbers, starting with the smallest line number and going to the 


largest. 


2.3 STATEMENTS 


Each line number is followed by a BASIC statement. The first 
word of a BASIC statement identifies the type of statement and informs 
BASIC of the operation to be performed and how to treat the data 
(if any) which follows the word. 


2.3.1 Multiple Statements on a Single Line 


More than one statement can be written on a single line as long 
as each statement (except the last) is terminated with a colon or a 
backslash. Thus only the first statement on a line can (and must) 


have a line number. For example: 
16 INPUT ALB. C 
is a single statement line, while: 
2@ LET H=K+1: PRINT Hoo. 2S IF Yee GoTo 18 


is a multiple-statement line containing three statements: a LET, a 
PRINT, and an IF-GOTO statement. 


Any statement can be used anywhere in a multiple-statement line 


except as noted in the discussion of the individual statements. 


2ede2 A Single Statement on Multiple Lines 


A single statement can be continued on successive lines of the 
program. To indicate that a statement is to be continued, the line 
is terminated with the LINE FEED key instead of the RETURN key. The 
LINE FEED performs a carriage return/line feed operation on the ter- 
minal and the line to be continued does not contain a line number. 
For example: 


16 LET WretW-e4e oe e-AY 
CA-B 2-173 


where the first line was terminated with the LINE FEED key is equiva- 
lent to: 
1@ LET WPRatW-K4e so eC 2-ACCA-BI-LP 


Note that the LINE FEED key does not cause a printed character to 
appear on the page. 


The length of a multiple-line statement is limited to 255 charac- 


ters. 2-3 


Where the LINE FEED key is used, it must occur between the ele- 
ments of a BASIC statement. That is, a BASIC verb or the designation 
of a subscripted array element (see Section 3.6.2), for example, 
cannot be broken with a LINE FEED, 


16 IF A1i=6 
THEN 166 


is acceptable where a LINE FEED follows @, but: 


1@ IF A 
1=@ THEN 146 
ILLEGAL CONDITIONAL CLAUSE 


is not acceptable nor is: 


16 IF Ad=@ THEN 1 
aa 
MODIFIER ERROR AT LINE 14 


and each illegal form generates an error message. A number of multi- 
word elements are processed as one word and cannot be broken by a 
LINE FEED. For example, AS FILE, FOR INPUT AS FILE, FOR OUTPUT AS 
FILE, GO TO, INPUT LINE, and ON ERROR GO TO are each treated by the 
system as one word. 


2.4 SPACES AND TABS 
Spaces can be used freely throughout the program to make state- 


ments easier to read. For example: 
18 LET B = Dee + 1 


instead of} 
1GLETR=D#24+4 
or 


The above statements are identical in effect. 


TABS, like spaces, are used to make a program easy to read. 
An example follows: 


1% FOR K=1 TO 3 


aa FOR IT=i TO 14 

38 FOR J=l TO 1% 

4A ACIsJ) = K/CItJ"1)+4+ACIsJ) 
5a NEXT Jf 

6A NEXT I 

7A NEXT K 


2.5 EXPRESSIONS 

An expression is a group of symbols which can be evaluated by 
BASIC. Expressions are composed of numbers, variables, functions, or 
a combination of the preceding separated by arithmetic, relational, 
or logical operators. 


The following are examples of expressions acceptable to BASIC- 


PLUS: 
Arithmetic Expressions Logical Expressions 
A X<Y 
A7* (Bt2+1) ((A>B) OR (C=D)) AND A/B<>C/D 


Not all kinds of expressions can be used in all statements, as is ex- 
plained in the sections describing the individual statements. In the 
following sections the reader is introduced to the elements which 


compose BASIC expressions. 


2.5.1 Numbers 

Numbers, called numeric constants because they retain a constant 
value throughout a program, can be positive or negative. Appendix F 
explains the integer and floating-point number formats. Numeric 


constants are written using decimal notation, as follows: 


+2 
-3.675 
1234.56 
-123456 
- - PPPPG1 


The following are not acceptable numeric constants in BASIC: 


However, BASIC can find the decimal expansion of those two mathemati- 


cal formulas as shown below: 


x is expressed as 14/3 
¥ 7 is expressed as SQR(7) 


These formats are explained in later sections. 


Scientific notation allows further flexibility in number 
representation. Numeric constants can be written using the 


letter E to indicate "times ten to the power," thus: 


-G9G123456 can be written in BASIC as 123.456E-6 
1234560996. can be written in BASIC as 123456E4 
~12345678999. can be written in BASIC as -1.2345679E19 


The E format representation of numbers is very flexible since a number 
such as .001 can be written as 1E-3, .01E-1, 1OOE-5, or any number of 
ways. If more than six digits are generated during any computation, 
the result of that computation is automatically printed in E format. 
(If the exponent is negative, a minus sign is printed after the E; 


if the exponent is positive, a space is printed: 1E-@4; 1E 94.) 


The combination E7, however, is not a constant, but a variable. 
The term 1E7 is used to indicate that 1 is multiplied by io" 


The range of floating-point numbers is (approximately) as follows: 


X= or in the range ro 2 < ABS(X) < io"e? 


2.5.2 Variables 


A variable is a data item whose value can be changed by the 
program. A numeric variable is denoted by a single letter or by a 
letter followed by a single digit. Thus BASIC interprets E8 as a 
variable, along with A, X, N5, L#, and Ol. (Subscripted, integer, and 


character string variables are described in later sections.) 


Variables are assigned values by LET, INPUT, and READ statements. 
The value assigned to a variable does not change until the next time 


a LET, INPUT or READ statement is encountered that contains a new 


value for that variable or when the variable is incremented by a FOR 
statement. (These conditions are explained further in later sections.) 
All variables are set equal to zero (%) before program execution. 

It is only necessary to assign a value to a variable when an initial 
value other than zero is required. However, good programming prac- 
tice would be to set variables equal to @ wherever necessary. This 


ensures that later changes or additions will not misinterpret values. 


2.5%3 Mathematical Operators 


BASIC automatically performs the mathematical operations of ad- 
dition, subtraction, multiplication, division and exponentiation. 
Formulas to be evaluated are represented in a format similar to stan- 
dard mathematical notation. There are five arithmetic operators used 


to write such formulas; they are as follows: 


Operator Examp le Meaning 
+ A+B Add B to A 
= A-B Subtract B from A 
* A*B Multiply A by B 
A/B Divide A by B 
4 AtB Calculate A to the B power, ne 


BASIC-PLUS permits the operator ** in place of + to denote the 


exponentiation operation. For example: 
A**B 


indicates the quantity A raised to the B power, ae, The ** operator 
is included for compatibility with some other BASIC processors. The 
symbol + is generally considered the BASIC symbol for exponentiation 


and is used throughout this manual. 


Unary plus and minus are also allowed, e.g. the - in -A+B or the 


+ in +X-Y. Unary plus is ignored. Unary minus is treated as explained 


below. 


When more than one operation is to be performed in a single formu- 
la, as is most often the case, rules are observed as to the precedence 
of the above operators. The arithmetic operations are performed in 


the following sequence, with (a) having the highest precedence: 


2-7 


a. Any formula within parentheses is evaluated before the 
parenthesized quantity is used in further computations. 
Where parentheses are nested, as follows: 


(A+ (B* (D+2))) 


the innermost parenthetical quantity is calculated first. 


b. In the absence of parentheses in a formula, BASIC performs 
operations as follows: 


1 exponentiation 

2. unary minus 

3. multiplication and division 
4. addition and subtraction 


Thus, for example, -AtB with a unary minus, is a legal 

expression and is the same as -(AtB). This implies that 
-242 evaluates as -4. The one extension of this rule is 
that the term At-B is allowed and is evaluated as At(-B). 


c. In the absence of parentheses in a formula involving more 
than one operation on the same level in (b) above, the 
operations are performed left to right, in the order that 
the formula is written. For example: 


A/B/C is evaluated as (A/B)/C 
A*B/C is evaluated as (A*B)/C 
The expression A+B*CtD is evaluated as follows: 


first, C is raised to the D power 
second, the result of the first operation is multiplied by B 
third, the result of the previous operation is added to A, 


Parentheses are used to indicate any other order of evaluation. For 
example, if it is the product of B and C that is to be raised to the 
D power, the expression would look as follows: 


A+ (B*C)+D 


If it is desired to multiply the quantity A+B by C to the D power: 
(A+B) *C+D 


The user is encouraged to use parentheses even where they are not 
strictly required in order to make expressions easier to read. Am- 
biguities can exist only in the programmer's mind, the computer always 


performs the operations as explained above. 


2.5.4 Relational Symbols 


Relational symbols are used in IF-THEN statements (see Section 3.5); 
in conditional FOR loops (see Section 8.6); and in IF, UNLESS, WHILE 
and UNTIL clauses (see Sections 3.5, 8.5, and 8.7) where it is neces- 
sary to compare values. The relational symbols are as follows (where 


A and B are variables or expressions): 


Mathematical BASIC 


Symbol Symbol Example Meaning 
= = =B A is equal to B 
< < A<B A is less than B 
< <= A<=B A is less than or equal to B 
> > A>B A is greater than B 
> >= A>=B A is greater than or equal to B 
# <> A<>B A is not equal to B 
x == A==B A is approximately equal to B. 


The term “approximately equal to" means that the two quantities 

look the same when printed. Within the computer, floating-point 
numbers can differ by a miniscule amount in the last decimal place 
but still be considered equal for all practical purposes. This last 
decimal place within the computer does not always cause two numbers 
to have a different value when printed. Numbers are carried inter- 
nally at greater than 6 digits of precision, but are rounded to 6 
digits for output or a * comparison. Thus, two numbers identical 
when rounded to 6 digits of precision are approximately equal, whereas 
two numbers equal to the internally carried limits of precision are 
truly equal (=). 


2.5.5 Logical Operators 
Logical operators are used in IF-THEN and such statements (see 


Section 3.5) where some condition is used to determine subsequent 
operations within the user program. For this discussion, A and B 


are relational expressions having only TRUE (-1) and FALSE (9) 
values. Logical operators can also be used in certain logical 


operations involving integers. (See Section 6.5 and 6.6.) The 
logical operators are as follows: 
Operator Example Meaning 

NOT NoT A The logical negative of A. If A is true, 


NOT A is false. 


AND A AND B The logical product of A and B. A AND B has 
the value true only if A and B are both true 
and has the value false if either A or B is 
false. 


OR | A ORB The logical sum of A and B. A OR B has the 
value true if either A or B is true and has 
the value false only if both A and B are 
false. 


XOR A XOR B The logical exclusive OR of A and B. A XOR B 
is true if either A or B is true but 
not both, and false otherwise. 


IMP A IMP B The logical implication of A and B. A IMP 
B is false if and only if A is true and B is 
false; otherwise the value is true. 


EQV A EQV B A is logically equivalent to B. A EQV B has 
the value TRUE if A and B are both true or 
both false, and has the value false otherwise. 


The following tables are called truth tables and describe graphi- 
cally the results of the above logical operations with both A and B 
given for every possible combination of values. 


A NOT A 


CHAPTER 3 


ELEMENTARY BASIC STATEMENTS 


This Chapter describes the simplest forms of the more elementary 
BASIC statements. These statements are sufficient, by themselves, for 
the solution of most problems. Once these statements are mastered, 
the user can investigate the more advanced applications of these state- 
ments and the additional statements and features explained in Parts 
II and III. 


The reader should understand that any problem which can be 
solved with the more advanced techniques can also be solved with the 
simpler statements, although the solution may not be as efficient. 
As long as the user understands the details of his problem he can 
represent it in BASIC on a number of levels ranging from the simple 
to the sophisticated. 


3.1 REMARKS AND COMMENTS 

It is often desirable to insert notes and messages within a user 
program. Such data as the name and purpose of the program, how to 
use it, how certain parts of the program work, and expected results at 
various points are useful things to have present in the program for 


ready reference by anyone using that program. 


There are two ways of inserting comments into a user program: 


a. the REMARK statement, and 


b. use of the exclamation mark (!) 


The word REMARK can be abbreviated to REM for typing convenience, 
and the message itself can contain any printing characters on the key- 
board. BASIC completely ignores anything on a line following the let- 
ters REM. (The line number of a REM statement can be used in a GOTO 
or GOSUB statement, see Sections 3.4 and 3.8.1, as the destination of 


a jump in program execution.) Typical REM statements are shown below: 


10 REM - THIS PROGRAM COMPUTES THE 
11 REM + ROUTS OF A QUADRATIC EQUATION 


The exclamation mark is normally used to terminate the executable 


part of a line and begin the comment part of the line. The ! character 
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can also begin the line, in which case the entire line is treated as a 


comment. For example: 


425 LET A=et+deSGkeC) 'SET A EQUAL TO INITIAL YALUE 

43@ PRINT Acett 'PRINT SECOND CALCULATED VALUE 

14@ !COMMENT 
In every statement other than the DATA statement, BASIC ignores every- 
thing on the line following the exclamation mark. An exclamation mark 
Must not appear on the same line as a DATA statement unless it is part 
of an item in the DATA statement. (Tabs are useful for inserting space 


between the statement and comment parts of a line to improve readability.) 


Messages in REMARK statements are generally called remarks, those 
after the exclamation mark, comments. Remarks and comments are printed 


when the user program is listed but do not affect program execution. 


The lines below indicate three ways of putting the same remark on 
two lines. Lines 10 and 11 are REM statements. Line 20 is one REM 
statement broken into two lines with the LINE FEED key. Line 30 is 
one comment (begun with a !) and broken into two lines with the LINE 
FEED key. 


4@ REM THIS PROGRAM COMPUTES THE 
41 REM ROOTS OF A BUADRATIC EQUATION 


2@ REM THIS PROGRAM COMPUTES THE 
ROOTS OF A GUAGRATIC EQUATION 


38 ! THIS PROGRAM COMPUTES THE 
ROOTS OF A GUADRATIC EQUATION 


3.2 LET STATEMENT 
The LET statement assigns a numeric value to a variable. Each 


LET statement is of the form: 


line number{LET}<variable>=<expresstion> 


This statement does not indicate algebraic equality, but performs the 
calculations within the expression (if any) and assigns the numeric 


value to the indicated variable. For example: 


4@ LET H=K+4 
26 LET Wea A4-HeoeC2-ACBo 


In line 10, the old value of X is increased by one and becomes the new 
value of X. In line 20, the formula on the right hand side is evalu- 


ated and the numeric value assigned to W2, 
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The LET statement can be a simple numerical assignment, such as 


or require the evaluation of a formula so long that it is continued on 


the next line (see Section 2.3.2). 


BASIC-PLUS allows the user to completely omit the word LET from 
the LET statement. The user may find it easier to type: 


1@ Hatoecse+?s 
than 
16 LET Hedeecs+7y 


This is a convenience and does not alter the effect of the statement. 


The LET statement can be used anywhere in a multiple statement 


line, for example: 


18 X=44: Y=X42+Y1: B2=3.5*A 


The LET statement allows the user to assign a value to multiple 
variables in the same statement. For example: 


40 LET #42 = 3.7 


causes each of the three variables to be set equal to 5.7. 


36:3 PROGRAMMED INPUT AND OUTPUT 


This Section describes the techniques used in performing BASIC 
program I/O (an abbreviation for the term Input/Output which includes 
the processes by which data is brought into and sent out of the computer). 
The most elementary forms of the PRINT, INPUT, READ, and DATA statements 
are presented here so that the user is able to create simple BASIC 


programs. 


Using the LET statement, already described, and the following 
executable statements, the user can easily write a BASIC program, 
If he should want to try his program, these simple I/O statements 


provide a means of obtaining tangible output. 


More advanced I/O techniques are described in Part III. 


3.3.1 READ, DATA, and RESTORE Statements 

READ and DATA statements are used to enter information into the 
user program during execution. A READ statement is used to assign to 
the listed variables those values which are obtained from a DATA state- 


ment. Neither statement is used without the other. 


A READ statement is of the form: 


line number READ <variable ltst> 
A DATA statement is of the form: 


line number DATA <value list> 


A READ statement causes the variables listed to be assigned se- 
quential values in the collection of DATA statements. Before the 
program is run, BASIC takes all DATA statements in the order they 
appear and creates a data block. Each time a READ statement is 
encountered in the program, the data block supplies the next value. 
If the data block runs out of data, the program is assumed to be fin- 
ished and an OUT OF DATA message is printed by BASIC. 


READ and DATA statements appear as follows: 


15@ READ KY. 2,51, te, 9 
330 DATA 4.2,4.7 
346 DATA 6. 7SE-3. ~-174. Set, F.144592¢ 


Note that only numbers are used in this particular DATA statement. 
(Input of string data is treated in Section 5.3.) The assignments 


performed by line 159 are as follows: 


X=4 

Y=2 

Z=1.7 
X1=6.73E-3 
Y2=-174.321 


Q9=3.1415927 


Since data must be read before it can be used in a program, READ 
statements normally occur near the beginning of a program. The loca- 
tion of DATA statements is arbitrary, as long as they occur in the 


correct order. A good practice is to collect all DATA statements 


near the end of the program. A DATA statement must be the only state- 
ment or the last statement on a line, while a READ statement can be 


placed anywhere in a multiple statement line. 


NOTE 


Comments are not permitted at the end of 
a DATA statement. 


If it should become necessary to use the same data more than 
once in a program, the RESTORE statement makes it possible to recycle 
through the complete set of DATA statements in that program, beginning 
with the lowest numbered DATA statement. The RESTORE statement is of 


the form: 
line number RESTORE 
For example: 
30 RESTORE 


causes the next READ statement following line 3 to begin reading data 
from the first DATA statement in the program, regardless of where the 


last data value was found. 


The same variable names can be used the second time through the 
data or not, as is most convenient, since the values are being read 
as though for the first time. In order to skip unwanted values, dummy 


variables must be read. In the following example, BASIC prints: 


4 1 2 3 


on the last line because it did not skip the value for the original 


N when it executed the loop beginning at line 45. 


LISTNH 

12 REM PROGRAM TO ILLUSTRATE USE OF RESTORE 
15 READ Ns PRINT “VALUES OF X ARE:" 

2@ FOR J=1 TO Ns READ X: PRINT X, 

25 NEXT I 

3@ RESTORE 

35 PRINT: PRINT “SECOND LIST OF X VALUES” 
48 PRINT “FOLLOWING RESTORE STATEMENT:" 

45 FOR I=1 TO Ns READ Xs: PRINT X, 


50 NEXT I 
62 DATA 4,1,2 
70 DATA 3,4 
3B END 
REALY 
RUNNH 
VALUES OF ¥ ARE: 
l 2 3 4 


SECOND LIST OF X VALUES 

FOLLOWING RESTORE STATEMENT: 

4 1 2 3 
READY 


3.3.2 PRINT Statement 


The PRINT statement is used to output data onto the terminal 
teleprinter. The general format of the PRINT statement is: 


line number PRINT {list} 


where the list can contain expressions, text strings, or both. As 
the braces indicate, the list is optional. Used alone, the PRINT 
statement: 

25 PRINT 


causes a blank line to be printed on the teleprinter (a carriage 


return/line feed operation is performed). 


PRINT statements can be used to perform calculations and print 
results. Any expression within the list is evaluated before a value 
is printed. Consider the following program: 


LISTNH 
19 LET A=l: LET B=2: LET C=3+A 


22 PRINT 
38 PRINT A+B+C 
READY 
RUNNH 
7 


READY 
All numbers are printed in the form: 


space) ~ 
( a ) <number> <space> 


The PRINT statement can be used anywhere in a multiple statement 
line. For example: 


18 A=l: PRINT As: A=A+5: PRINT: PRINT A 


would cause the following to be printed on the terminal when executed: 


RUNNH 


READY 


Notice that the teleprinter performs a carriage return/line feed at the 
end of each PRINT statement. Thus the first PRINT statement causes a l 
and a carriage return/line feed, the second PRINT statement is respon- 
sible for the blank line, and the third PRINT statement causes a 6 and 


another carriage return/line feed to be output. 


BASIC considers the terminal printer to be divided into five zones 
of fourteen spaces each’. When an item in a PRINT statement is followed 
by a comma, the next value to be printed appears in the next available 
print zone. For example: 

19 LET Az=3: LET B2 
2@ PRINT A,B,A+B,A*B,A-B,B-A 


When the preceding lines are executed, the following is printed: 


3 2 5 6 | 
-1 


Notice that the sixth element in the PRINT list is printed as the 
first entry on a new line, since a 72-character line has five print zones. 


Two commas together in a PRINT statement cause a print zone to be 
skipped. For example: 

LISTNH 

18 LET A=i!: LET B= 

26 PRINT A,B,,A+B 

READY 


RUNNH 
I 


READY 


If the last item in a PRINT statement is followed by a comma, no 
carriage return/line feed is output, and the next value to be printed 
(by a later PRINT statement) appears in the next available print zone. 
For example: 

LISTNH 
1@ A=13:B=2:C=3 
28 PRINT A,:PRINT Bs: PRINT C 
READY 
RUNNH 
I 
3 


READY 


‘Terminals with greater than 83 columns have additional print zones 
in units of fourteen spaces. 
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If a tighter packing of printed values is desired, the semicolon 
character can be used in place of the comma. A semicolon causes no 
further spaces to be output. A comma causes the print head to move 
at least one space to the next print zone or possibly perform a car- 
riage return/line feed. The following example shows the effects of 


the semicolon and comma. 


LISTNH 

19 LET Azls Br2: C=3 
28 PRINT AsB;C; 

32 PRINT A+i3B+13C+l 
48 PRINT A,B,C 


READY 


RUNNH 
ft 23 2 3 4 
1 2 3 


READY 


The PRINT statement can be used to print a message, either alone 
or together with the evaluation and printing of numeric values. Charac- 
ters are indicated for printing by enclosing them in single or double 
quotation marks (therefore each type of quotation mark can only be 
printed if surrounded by the other type of quotation mark). For 
example: 

LISTNH 


1@ PRINT “TIME’S UP" 
28 PRINT '"NEVERMORE™' 


READY 

RUNNH 
TIME’S UP 
“NEVER MORE” 


READY 


As another example, consider the following line: 


4@ PRINT "AVERAGE GRAGE TS"; & 


which prints the following (where X is equal to 83.4): 


RAYERAGE GRADE IS &2. 4 


When a character string is printed, only the characters between 
the quotes appear; no leading or trailing spaces are added. Leading 
and trailing spaces can be added within the quotation marks using the 
keyboard space bar; spaces appear in the printout exactly as they are 
typed within the quotation marks. 
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When a comma separates a text string from another PRINT list item, 
the item is printed at the beginning of the next available print zone. 
Semicolons separating text strings from other items are ignored. Thus, 


the previous example could be expressed as: 


4@ PRINT “AVERAGE GRADE IS" X 


and the same printout would result. A comma or semicolon appearing 
as the last item of a PRINT list always suppresses the carriage re- 


turn/line feed operation. 


The following example demonstrates the use of the formatting 


characters, and ; with text strings: 


123 PRINT “STUDENT NUMBER'Xs "GRADE ="G3"AVYEe =MAS 
139 PRINT "NO.e IN CLASS =''N 


could cause the following to be printed (assuming calculations were 


done prior to line 130): 


STUDENT NUMBER 11908549 GRADE = 67 AVEs = 85e44 NOs IN CLASS = 26 


3.3.3 INPUT Statement 

The second way to input data to a program is with an INPUT state- 
ment. This statement is used when writing a program to process data 
to be supplied while the program is running. During execution, the 
programmer can type values as the computer asks for them. (Non- 
terminal INPUT is described in Part III.) Depending upon how many 
values are to be accepted by the INPUT command, the programmer may 
wish to send himself a message reminding him what data is to be 
typed at what time (this can be done with the PRINT or INPUT statement). 


The INPUT statement is of the form: 
line number INPUT <list> 
For example: 
14 INPUT 45RsC 
causes the computer to pause during execution, print a question mark, 
and wait for the user to type three numeric values separated by 


commas. The values typed are entered to the computer by typing the 
RETURN key or the ESCAPE key (ESC on some terminals, ALT MODE on others). 


In the example program following, four questions are asked at 
execution time: INTEREST IN PERCENT?, AMOUNT OF LOAN?, NUMBER OF 
YEARS?, and NO. OF PAYMENTS PER YEAR?. The programmer knows which 
value is requested and proceeds to type and enter the appropriate 


value. 


LISTNH 

12 REM PROGRAM TO COMPUTE INTEREST PAYMENTS 
15 INPUT "INTEREST IN PERCENT™$ J 

26 LET J=J/198 

25 INPUT "AMOUNT OF LOAN"; A 

30 INPUT “NUMBER OF YEARS"; N 

35 INPUT “NO. OF PAYMENTS PER YEAR"; M™ 

4@ N=NkMs IsJ/M: Brlt+I: R=A*I/C1-1/BtN) 

45 PRINT: PRINT “AMOUNT PER PAYMENT ="5R 

5@ PRINT “TOTAL INTEREST =" sR*N-A 

55 PRINT: B-A 

6@ PRINT “INTEREST APP TO PRIN BALANCE OF PRIN” 
65 L=B*I: P=R-L: B-B-P 

67 PRINT L,P,B 

76 IF B>=R GOTO 65 

75 PRINT B*1,R-B*l 

8@ PRINT “LAST PAYMENT WAS "B*I+B 

85 END 


READY 


RUNNH 

INTEREST IN PERCENT? 9 
AMOUNT OF LOAN? 2588 

NUMBER OF YEARS? 2 

NO. OF PAYMENTS PER YEAR? 4 


AMOUNT PER PAYMENT = 344.961 
TOTAL INTEREST = 259.688 


INTEREST APP TO PRIN BALANCE OF PRIN 


56.25 288.711 2211.29 
49.754 295.207 1916.88 
43.1119 541,849 1614.23 
36.3282 388.641 1395.59 
29.3758 315,585 998.967 
22.2752 522.686 667.321 
15.8147 329.946 337.375 
7.59893 337.37 


LAST PAYMENT WAS 344.966 
READY 


As in the previous program, the question mark generated by BASIC 
is grammatically useful if a printed question is to prompt the typing 


of the input values. 


The output for the program begins after the word RUNNH and in- 
cludes a verbal description of the numbers. This verbal description 
on the output is optional with the programmer, although it has a def- 


inite advantage in ease of use and understanding. 


When the correct number of variables have been typed in answer 
to the printed ? character, type the RETURN key to enter the values to 
the computer. If too few values are listed, the computer prints 
another ? to indicate that more data is requested. If too many values 


are typed, the excess data on that line is ignored. 


Messages to be printed at execution time can be inserted within 
the INPUT statement itself. The message is set off by single or dou- 
ble quotes from the other arguments of the INPUT statement. For example 


1Q INPUT "YOUR AGE IS "3A 


is equivalent to 


1@ PRINT "YOUR AGE IS "3 
eG INPUT 64 


The use of the comma or semicolon character (or no character) to 
separate a character string to be printed from input variable names is 
analogous to the PRINT statement (see Section 3.3.2). 


3.4 UNCONDITIONAL BRANCH, GOTO STATEMENT 

The GOTO statement is used when it is desired to unconditionally 
transfer to some line other than the next sequential line in the pro- 
gram. In other words, a GOTO statement causes an immediate jump to a 
specified line, out of the normal consecutive line number order of 


execution. The general format of the statement is as follows: 
line number GOTO <line number> 


The line number to which the program jumps can be either greater than 
or less than the current line number. It is thus possible to jump 


forward or backward within a program. 


Consider the following simple example: 


18 LET A=2 

28 GOTO 52 

38 LET A=SQR(A+14) 
5@ PRINT A,A*A 


When executed, the above lines cause the following to be printed: 


2 4 


When the program encounters line 20, control transfers to line 50; 
line 50 is executed, control then continues to the line following line 


50. Line 30 is never executed. Any number of lines can be skipped in 
either direction. 


When written as part of a multiple statement line, GOTO should 
always be the last statement on the line, since any statement fol- 


lowing the GOTO on the same line is never executed. For example: 


110 LET A=ATNCR2): PRINT At GOTO 54 


3.5 CONDITIONAL BRANCH, IF-THEN AND IF-GOTO STATEMENTS 

The IF-THEN and IF-GOTO statements are used to transfer condition- 
ally from the normal consecutive order of statement numbers, depending 
upon the truth of some mathematical relation or relations. The basic 
format of the IF statement is as follows: 


THEN<s tatement> 
line number IF <conditton> THEN<Zine number> 


GOTO<Zine number> 


The specified condition is tested. If the relationship is found false, 
then control is transferred to the statement following the IF state- 
ment (the next sequentially numbered line). If the condition is true, 
the statement following THEN is executed or control is transferred to 
the line number given after THEN or GOTO. (An extension of this state- 


ment, the IF-THEN-ELSE statement, is described in Section 8.5.) 


The deciding condition can be either a simple relational expres- 
sion in which two mathematical expressions are separated by a rela- 
tional operator, or a logical expression in which two relational or 


logical expressions are separated by a logical operator. For example: 


Relational Expression Logical Expression 
At+2>B A>B AND B<=SQR(C) 


Both types of condition, when evaluated, are either true or false; no 
numeric value is associated with the results of an IF statement. The 
relational and logical operators are described in Sections 2.5.4 and 


2.5.5 and are presented in Appendix A for reference. 
79 IF A*B>=B*(R+1) THEN LET D4=bD4+1 


In the above line the quantities A*B and B*(Bt+l) are compared. If the 
first value is greater than or equal to the second value, the variable 
D4 is incremented by 1. If B*(B+l) is greater than A*B, D4 is not incre- 


mented and control passes immediately to the next line following line 75. 


When a line number follows the word THEN, the IF-THEN statement 
is the same as the IF-GOTO statement. The word THEN can be followed 
by any BASIC statement, including another IF statement. For example: 


25 IF A> THEN IF B>C THEN PRINT "A>BeC" 
25 IF A>B AND BoC THEN PRINT "“A>BeC" 


The preceding two lines are logically equivalent and perform the fol- 


lowing operation: 
if B is both less than A and greater than C, the message 
A>B>C 


is printed, otherwise the line following line 25 is executed. 


In the following example, the IF-GOTO statement in line 20 is 
used to limit the value of the variable A in line 10. Execution of 
the loop continues until the relationship A>4 is true, then immediately 
branches to line 55 to end the program. {A program loop is a series 
of statements which are written so that, when the statements have been 
executed, control transfers to the beginning of the statements. This 


process continues to occur until some terminal condition is reached.) 


LISTNH 

10 LET AzA+l: X=At2 

2@ IF A>4 GOTO 55 

25 PRINT xX 

38 PRINT "VALUE OF A IS" A 
48 GOTO 198 

55 END 


READY 


when the above loop is executed, the following is printed: 


RUNNH 
VALUE OF AIS 1 
VALUE OF AIS 2 
VALUE OF A IS 3 
VALUE OF AIS 4 
READY 


(The novice BASIC programmer is advised to follow the operation of the 


computer through these short example programs.) 


In IF statements, the following priorities are associated with 
each operator, in order to provide unambiguous evaluation of the con- 


ditions specified (where a. has the highest priority): 


a. expressions in parentheses 
intrinsic or user-defined functions 
c. exponentiation (t+) 


unary minus (-), that is, a negative number or 
variable such as -3, -A, etc. 


multiplication and division (* and /) 

addition and subtraction (+ and -) 

relational operators (=, <, <=, >, >=, ==, <>) 
NOT 

AND 

OR and XOR 

IMP 

EQV 


How UE oO OQ oF 


Within the operators indicated in any one group above, operations pro- 


ceed from left to right. 


Examples of IF-THEN statements follow: 


19 IF A>B THEN 149 !SIMPLE COMPARISON 
24 IF A=B OR BeC THEN 2aa4 
34 IF A>B THEN A=-B !ASSIGNMENT BY A LET STATEMENT 


40 IF X>Y IMP Y>Z THEN PRINT "QED" 


An IF statement would normally be the last statement on a multiple 
statement line (to avoid confusion); however, the following rules 
govern the transfer path of the IF statement in other positions: 


a. The physically last THEN clause is considered to be fol- 
lowed by the next statement (or statements) on the line: 


10 IF A=1 THEN PRINT As:PRINT “TRUE CASE": GOTO 29 
15 PRINT "NOT = 1" 


where A#1, the following line is printed: 
NOT =1 

where A=1, the following line is printed: 
1 TRIUE CASE 


b. All other THEN clauses are considered to be followed 
by the next line of the program: 


26 IF A>R THEN IF B>C THEN PRINT "Rec: GOTO 3a 
25 PRINT "ac=ne 


Only in the case where "B>C" is printed is the state- 
ment GOTO 3@ seen and executed. 


3.6 PROGRAM LOOPS 


Loops were first mentioned in the section on the IF-THEN 
and IF-GOTO statement. Programs frequently involve performing cer- 
tain operations a specific number of times. This is a task for which 
a computer is particularly well suited. With simple tasks, such as 
computing a list of prime numbers between 1 and 1,000,000, a computer 
can perform the operations and obtain correct results in a minimal 
amount of time. To write a loop, the programmer must ensure that the 


series of statements is repeated until a terminal condition is met. 


Programs containing loops can be illustrated by using two ver- 
sions of a program to print a table of the positive integers 1 through 
100 together with the square root of each. Without a loop, the first 


program is 101 lines long and reads: 


1@ PRINT 1s SQRC1) 
2A PRINT 25 SORC2) 
309 PRINT 3s SOQRC3) 


99@ PRINT 99, SQRC99) 
1066 PRINT 1085 SOQRC19@) 
181% END 


With the following program example, using a simple sort of loop, 


the same table is obtained with fewer lines: 


19 LET X=1 

20 PRINT XsSORCK) 

39 LET X=X+1 

49 IF X<=190 THEN AG 
50 END 


Statement 10 assigns a value of 1 to X, thus setting up the initial 
conditions of the loop. In line 20, both 1 and its square root are 
printed. In line 30, X is incremented by 1. Line 40 asks whether X 
is still less than or equal to 100; if so, BASIC returns to print the 
next value of X and its square root. This process is repeated until 
the loop has been executed 100 times. After the number 100 and its 
square root have been printed, X becomes 101, The condition in line 40 
is now false so control does not return to line 20, but goes to line 50 


which ends the program. 
All program loops have four characteristic parts: 


a. initialization, the conditions which must exist for the 
first execution of the loop (line 10 above); 


b. the body of the loop in which the operation which is 
to be repeated is performed (line 20 above); 


Comm modification, which alters some value and makes each 
execution of the loop different from the one before 
and the one after (line 30 above); 


d. termination condition, an exit test which, when satisfied, 
completes the loop (line 40 above). Execution continues to 
the program statements following the loop (line 50 above). 


3.6.1 FOR and NEXT Statements 
The FOR statement is of the form: 


line number FOR <vartable>=<expression> TO <expression> {STEP <expresston>} 


For example: 
4@ FOR K=2 TG 2@ STEF 2 


which causes program execution to cycle through the designated loop 
using K as 2, 4, 6, 8,..-, 20 in calculations involving K. When K=20, 
the loop is left behind and the program control passes to the line fol- 
lowing the associated NEXT statement. The variable in the FOR state- 


ment, K in the preceding example, is known as the control variable. 


The control variable must be unsubscripted, although a common use 
of such loops is to deal with subscripted variables using the control 
variable as the subscript of a previously defined variable (this is 
explained in further detail in Section 3.6.2). The expressions in the 
FOR statement can be any acceptable BASIC expression as defined in 
Section 2.5. 


The NEXT statement signals the end of the loop which began with 
the FOR statement. The NEXT statement is of the form: 


line number NEXT <vartable> 


where the variable is the same variable specified in the FOR statement. 
Together the FOR and NEXT statements describe the boundaries of the 
program loop. When execution encounters the NEXT statement, the com- 
puter adds the STEP expression value to the variable and checks to see 

if the variable is still less than or equal to the terminal expression 
value. When the variable exceeds the terminal expression value, con- 
trol falls through the loop to the statement following the NEXT statement. 


If the STEP expression is omitted from the FOR statement, +1 is 
the assumed value. Since +l is a common STEP value, that portion of the 


statement is frequently omitted. 


The expressions within the FOR statement are evaluated once upon 
initial entry to the loop. The test for completion of the loop is made 
prior to each execution of the loop. (If the test fails initially, the 


loop is never executed.) 


The control variable can be modified within the loop. When control 
falls through the loop, the control variable retains the last value used 
within the loop. 


The following is a demonstration of a simple FOR-NEXT loop. The 
loop is executed 10 times; the value of I is 10 when control leaves the 
loop; and +l is the assumed STEP value: 

19 FOR I=1 TO 14 
2 PRINT I 


34 NEXT I 
4 PRINT I 


The loop itself is lines 10 through 30. The numbers 1 through 10 are 
printed when the loop is executed. After I=10, control passes to line 
40 which causes 10 to be printed again. If line 10 had been: 


19 FOR I = 1@ TO 1 STEP -1 


the value printed by line 40 would be l. 


1¢ FOR 1 = 2 TO 44 STEP 2 
26 LET I = 44 
34 NEXT 1 


The above loop is only executed once since the value of I=44 has been 


reached and the termination condition is satisfied. 


If, however, the initial value of the variable is greater than 
the terminal value, the loop is not executed at all. A statement 


of the format: 
16 FOR I = @@ TO 2 STEP 2 


cannot be used to begin a loop, although a statement like the follow- 


ing will initialize execution of a loop properly: 
19 FOR 1=20 TO 2 STEP -2 


For positive STEP values, the loop is executed until the control 
variable is greater than its final value. For negative STEP values, 
the loop continues until the control variable is less than its final 


value. 


FOR loops can be nested but not overlapped. The depth of nesting 
depends upon the amount of user storage space available (in other 
words, upon the size of the user program and the amount of core each 
user has available). Nesting is a programming technique in which one 
or more loops are completely within another loop. The field of one 
loop (the numbered lines from the FOR statement to the corresponding 


NEXT statement, inclusive) must not cross the field of another loop. 


ACCEPTABLE NESTING UNACCEPTABLE NESTING 
TECHNIQUES TECHNIQUES 


Two Level Nesting 


FOR Il = 1 TO 19 FOR Il = 1 TO 19 

(FOR I2=1T0 19 FOR 12 = 1 TO 19 
NEXT 12 NEXT I1 

(FOR I3=1T0 19 NEXT I2 
NEXT 13 
NEXT I1 

Three Level Nesting 

FOR Il = 1 TO 1g FOR Il = 1 TO 19 
FOR I2 = 1 TO 19 FOR I2 = 1 TO 19 
FOR 13 = 170 19 FOR I3 = 1 TO 19 
NEXT I3 NEXT 13 
FOR 14 = 1 TO 19 FOR I4 = 1 TO 19 
NEXT 14 NEXT 14 
NEXT I2 NEXT I1 
NEXT I1 NEXT 12 


An example of nested FOR-NEXT loops is shown below: 


5 DIM xO5519) 

14 FOR A=1 TO 5 

efi FOR B=2 TG 1% STEP 2 
38 LET KXC&sB)= A+B 

4@ NEXT B 

5% NEXT A 

55 PRINT x€551@) 


Upon execution of the above statements, BASIC prints 15 when line 


55 is processed. 


It is possible to exit from a FOR-NEXT loop without the control 
variable reaching the termination value. A conditional or uncondition- 
al transfer can be used to leave a loop. Control can only transfer 
into a loop which had been left earlier without being completed, en- 


suring that termination and STEP values are assigned. 


Both FOR and NEXT statements can appear anywhere in a multiple 


statement line. For example: 


i@ FOR I=1 TO 18 STEP 5: NEXT I: PRINT "I="31 


causes: 


to be printed when executed. 


Neither the FOR nor NEXT statement can be executed conditionally in 


an IF statement. The following statements are incorrect: 


15 IF I<>J THEN NEXT I 
16 IF T=J THEN FOR IT=1 TO J 


3.6.2 Subscripted Variables and the DIM Statement 


In addition to the simple variables which were described in 
Chapter 2, BASIC allows the use of subscripted variables. Subscripted 
variables provide the programmer with additional computing capabili- 
ties for dealing with lists, tables, matrices, or any set of related 


variables. In BASIC, variables are allowed one or two subscripts. 


The name of a subscripted variable is any acceptable BASIC vari- 
able name followed by one or two integer expressions in parentheses. 


For example, a list might be described as A(I) where I goes from 1 


to 5 as shown below (all matrices are created with a zero element, 
even though that element is never specified): 


A(f), A(1), A(2), A(3), A(4), A(5) 


This allows the programmer to reference each of six elements in the 


list, which can be considered a one dimensional algebraic matrix as 
follows: 


A two dimensional matrix B(I,J) can be defined in a similar man- 
ner and graphically illustrated as follows: 


a(32) | 23,3) [7 
ee, 


B(z,1) { 3(t,2) [ B(t,3) | NLD 
Subscripts used with subscripted variables throughout a program can 
be explicitly stated or be any legal expression. 


It is pdéssible to use the same variable name as both a sub- 
scripted and an unsubscripted variable. Both A and A(I) are valid 
variables and can be used in the same program. However, BASIC does 
not accept the same variable name as both a singly and a doubly sub- 
scripted variable name in the same program (A(I) and A(I,@) would 
refer to the same data item). 


A dimension (DIM) statement is used to define the maximum 


number of elements in a matrix. ("Matrix" is the general term 
used in this manual to describe all the elements of a subscripted 
variable.) The DIM statement is of the form: 


line number DIM <vartable (n)>,<vartable(n,m)>,... 


Where the variables specified are indicated with their maximum sub- 


script value(s). 


For example: 


16 DIM X€5)» Y¥C4s2)5 AC1G,1@) 
12 DIM 14¢189) 
Only integer values (such as 5 or 5070) can be used in DIM 
statements to define the size of a matrix. Any number of matrices 
can be defined in a single DIM statement as long as their 


representations are separated by commas. 


If a subscripted variable is used without appearing in a DIM 
statement, it is assumed to be dimensioned to length 10 in each dimen- 
sion (that is, having eleven elements in each dimension, 9g through 19). 
However, all matrices should be correctly dimensioned in a program. 

DIM statements are usually grouped together among the first lines of 
a program. 


The first element of every matrix is automatically assumed to 
have a subscript of zero. Dimensioning A(6,10) sets up room for a 
matrix with 7 rows and 11 columns. This zero element is illustrated 


in the following program: 


LISTNH 

1@ REM - MATRIX CHECK PROGRAM 
28 DIM AC6,1@) 

30 FOR I=8 TO 6 

4@ LET ACI,@) = 1 

5@ FOR J:@ TO 19 

68 LET AC@,Jd) = J 

78 PRINT ACIyd)3 

8@ NEXT J: PRINT: NEXT I 


9@ END 
READY 
RUNNH 
® 123 4 5 6 7 8 9 16 
186 6 @ 6 6B G6 @ B 
20802 @ 6 6 8 @ 6 BB 
3 86 686 8 @ @ @ @ @ @ B 
406606 8 0808 8 @ 8 @ 
5 8 @ @ @ @ 868 8 BB B 
6 6686 8686 8 @ @ @ 


READY 


Notice that a variable has a value of zero until it is assigned a 


value. 


If the user wishes to conserve core space he may make use of 
the extra variables set up within the matrix. He could, for 
example, say DIM A(5,9) to obtain a 6 x 10 matrix which would then 


be referenced beginning with the A(f,f) element. 


The size and number of matrices which can be defined depend 


upon the amount of user storage space available. 


Additional information on matrices can be found in Chapter 7. 


A DIM statement can be placed anywhere in a multiple statement 
line. A DIM statement can appear anywhere in the program and need 
not appear prior to the first reference to an array, although DIM 
statements are generally among the first statements of a program 
to allow them to be easily found if any alterations are later 
required. 


3.7 MATHEMATICAL FUNCTIONS 


Within the course of a user's programming experience, he 
encounters many cases where relatively common mathematical operations 
are performed. The results of these common operations can often be 
found in volumes of mathematical tables; i.e., sine, cosine, square 
root, log, etc. Since it is this sort of operation that computers 
perform with speed and accuracy, such operations are built into 
BASIC. The user need never consult tables to obtain the value of 
the sine of 23° or the natural log of 144. When such values are 


to be used in an expression, intrinsic functions, such as: 


SIN (23*PI/186) 
LOG (144) 


are substituted. 


The various mathematical functions available in BASIC-PLUS 
are detailed in Table 3.1. 


Table 3—1 
Mathematical Functions 


Meaning 


returns the absolute value of X 
returns the sign function of X, a value 
of 1 preceded by the sign of X, SGN(#)=9 
returns the greatest integer in X which is 
less than or equal to X, (INT(-.5)=-1) 
returns the truncated value of xX, 
SGN (X) *INT (ABS (X)) , (FIX(-.5)=9) 


7 £ vv . waAdaance 
returns the cosine of X in radians 


Function 
Code 


ABS (X) 
SGN (X) 


INT (X) 


FIX (X) 


COs (XxX) 


UU , A 


SIN (X) returns the sine of X in radians 

TAN (X) returns the tangent of X in radians 

ATN (X) returns the arctangent (in radians) of xX 

SOR (X) returns the square root of X 

EXP (X) returns the value of e+X, where e=2.71828... 
LOG (X) returns the natural logarithm of xX, log_x 
LOG1# (X) returns the common logarithm of xX, Log, 9X 
PL has a constant value of 3.1415927 


RND (X) returns a random number between @ and 1; 
the same sequence of random numbers is 
generated each time a program is run 
requiring the use of the random number 
generator. The value of X is ignored. 
alternate form for calling the random number 


function. 


Most of these functions are self-explanatory. Those which are 


not are explained in the following section. 


3.7.1 Examples of Particular Intrinsic Functions 


Sign Function, SGN(X) 


The sign function returns the value +1 if X is a positive value, 


@ if X is 0, and -1 if X is negative. For example: SGN (3.42) = 1, 
SGN (-42) = -1, and SGN(23-23) = @. 

LISTNH 

18 REM - SGN FUNCTION EXAMPLE 

28 READ A,B 


25 PRINT “A="A,"B="B 

38 PRINT “SGNCA)="SGN(A),” SGNCB) =" SGN (B) 
40 PRINT “SGNCINTCA))="SGNCINTCA)) 

58 DATA -7.352, 2 44 


6@ END 

READY 

RUNNH 

A=-7.32 B= ,44 
SGNCA)=-1 SGN(B)= 1 


SGNCINT(A))=-1 
READY 


Integer Function, INT (X) 
The integer function returns the value of the greatest integer 


not greater than X. For example, INT(34.67) = 34. INT can be used 
to round numbers to the nearest integer by asking for INT(X+.5). For 
example, INT(34.67+.5) = 35. INT can also be used to round to any 


given decimal place, by asking for 
INT (X*194+ D+.5)/19+tD 


where D is the number of decimal places desired, as in the following 


program: 


LISTNH 

16 REM- INT FUNCTION EXAMPLE 

2@ PRINT "NUMBER TO BE ROUNDED"; 
38 INPUT A 

48 PRINT "NO. OF DECIMAL PLACES"; 
5@ INPUT D 

69 LET B=INTCA*161D+.5)/18TD 

70 PRINT “A ROUNDED ="B 

88 GO TO 28 

92 END 


READY 


RUNNH 

NUMBER TO BE ROUNDED? 55,65342 
NO, OF DECIMAL PLACES? 2 

A ROUNDED = 55.65 

NUMBER TO BE ROUNDED? 78.375 
NO. OF DECIMAL PLACES? -2 

A ROUNDED = 188 

NUMBER TO BE ROUNDED? 67.89 
NO. OF DECIMAL PLACES? -1 

A ROUNDED = 78 

NUMBER TO BE ROUNBED? tC 


READY 


For negative numbers, the largest integer contained in the number 
is a negative number with the same or a larger absolute value. For 
example: INT(-23)= -23, but INT(-14.39) = -15. 


NOTE 


+C in the above program terminates 
program execution. See the RSTS-11 


System User's Guide. 


Random Number Function, RND(X) 

The random number function produces a random number between 0 and 
1. The numbers are reproducible in the same order for later checking 
of a program. The argument X in the RND(X) function call can be any 


number, as that value is ignored. 


LISTNH 

19 REM - RANDOM NUMBER EXAMPLE 
25 PRINT "RANDOM NUMBERS" 

38 FOR I=1 TO 33 

4@ PRINT RND(@), 


5Q@ NEXT I 

62 END 

READY 

RUNNH 

RANDOM NUMBERS 

o771827 78183 oT5174 473969 ©781555E=1 
«283217 25159 «266449 0955597 23355541 
«412872 0457367 -283588E-1 -538825E-1 S765 75E-1 
0921722 0921417 +233882 «185255 0534515 
0259796 748138 152665 0178746 -668488 
©474213 «828888 2785414 772491 2286224 

READY 


In order to obtain random digits from 0 to 9, change line 40 to read: 


40 PRINT INTC1@*RND(B)), 


and tell BASIC to run the program again. This time the results are: 


RUNNH 

RANDOM NUMBERS 

7 7 7 4 g 

2 5 2 9 3 

4 4 8 @ 8 

S i] 2 1 5 

2 7 | 1 6 

4 8 7 7 2 

READY 
It is possible to generate random numbers over any range. For exam- 


ple, if the range (A,B) is desired, use: 
(B-A) *RND (9) +A 


to produce a random number in the range A<n<B. 


Since the parameter X in RND(X) is ignored, there is an alternate 
means of calling the random number generator having no arguments: RND. 


The following line is, therefore, acceptable: 


4@ PRINT FENG, 
Similarly, if a number in the range (A,B) is desired, the formula: 
(B-A) *RND+A 


can be used. 


3.7.2 RANDOMIZE Statement 
The RANDOMIZE statement is written as follows: 


line number RANDOMIZE 


or, alternatively: 


line number RANDOM 


If the random number generator is to calculate different random 
numbers every time a program is run, the RANDOMIZE statement is used. 
RANDOMIZE is placed before the first use of random numbers (the RND 
function) in the program. When executed, RANDOMIZE causes the RND 
function to choose a random starting value, so that the same program 
run twice gives different results. For this reason, it is a good 
practice to debug a program completely before inserting the RANDOMIZE 


statement. 


To demonstrate the effect of the RANDOMIZE statement on two runs 
of the same program, we insert the RANDOMIZE statement as statement 15 
in the following program: 
LISTNH 
15 RANDOMIZE 


28 FOR I=1 To 5 
25 PRINT “VALUE” I “ IS" RND(@) 


38 NEXT I 

35 END 

READY 

RUNNH 

VALUE 1 IS .797943 
VALUE 2 IS .388879 
VALUE 3° IS .618988 
VALUE 4 IS .132141E-1 
VALUE 5 IS .588392 
READY 
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RUNNH 
VALUE 1 IS .273@41 
VALUE 2 IS .225372 


VALUE 3. IS .894867 
VALUE 4 IS ,34@851 


VALUE 5 IS .9913083 
READY 


The output from each run is different. 


3.743 User-Defined Functions 

Tn some programs it may be necessary to execute the same sequence 
of statements or mathematical formulas in several different places. 
BASIC allows the programmer to define his own functions and call these 
functions in the same way he would call the square root or trig 


functions. 


These user-defined functions consist of a function name: the 
first two letters of which are FN followed by any valid variable name. 


For example: 


FNA 
FNAL 


The function can be defined anywhere in the program, even be- 
fore its first use. The defining or DEF statement is formed as 
follows: 

line number DEF FNa(arguments) = <expresston (arguments)> 
where a is any legal variable name. The arguments may consist of 
zero to five dummy variables. The expression, however, need not con- 
tain all the arguments and may contain other program variables not 


among the arguments. For example: 
1g DEF FNA(S) = S*2 
causes a later statement: 
28 LET R = FNA(4)+1 


to be evaluated as R=17. As another example: 


S@ DEF FNBCARL Bs = Atave 
6H Y=FNBidd 4, R33 


causes the function to be evaluated with the current value of the 
variable X within the program. In this case the dummy argument B 


(which becomes the actual argument R3 in the function call) is unused. 
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The two following programs 


EeOgr ots 
LISTNH 
1@ DEF FNSCA) = ATA 
28 FOR I=1 To 5 
38 PRINT I, FNS(I) 
4B NEXT I 
5@ END 


READY 
Program #2: 
LISTNH 
1@ DEF FNS(X) = X*tX 
26 FOR I=) To 5 
3@ PRINT I, FNSCI) 
48 NEXT I 
5@ END 


READY 
cause the same output: 


RUNNH 

1 1 

2 4 

3 27 

4 256 
5 3125 


REaDY 
The arguments in the DEF statement can be seen to have no signif- 
icance; they are strictly dummy variables. The function itself can 
be defined in the DEF statement in terms of numbers, variables, other 
functions, or mathematical expressions. For example: 
C+ EaN + 


FNACKI AE + FNAC KH? 
SQRCatdo +4 


16 DEF FNACKS 
26 DEF FNECK> 
30 DEF FNCCKS 


uo tt 


The statement in which the user-defined function appears can have 
that function combined with numbers, variables, other functions, or 


mathematical expressions. For example: 
48 LET R = FRACKEYF SEN ACY Sto 


A user-defined function can be a function of zero to five vari- 


ables, as shown below: 
#5 DEF FNLGs. , 23 = SURCH ES + YOR + E7E? 


A later statement in a program containing the above user-defined 


function might look like the following: 
as LET B = FNLEG, L, eo 


where D, L, and R have some values in the program. 
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LISTNH 

1 ! MODULUS ARITHMETIC PROGRAM 

p) ! FIND X MOD ™ 

1@ DEF FNM(X,M) = X-MEINT(X/™) 

15 3 

2@ 1 FIND A+B MOD ™ 

25 DEF FNACA,B,M) = FNMCA+B,™) 

36 I 

35 |! FIND A*B MOD M 

48 DEF FNBCA,B,™) = FNM(CA*B,™) 
! 


45 PRINT 

5@ PRINT “ADDITION AND MULTIPLICATION TABLES, MOD M™ 
55 INPUT “GIVE ME AN M™3M 

S@ PRINT: PRINT "ABDITION TABLES MOD "M 


7@ FOR 1-8 TO Me] 

75 PRINT Is" "3 

82 FOR J=@ TO Mel 

85 PRINT FNACI,d,™)3 

9@ NEXT Js PRINT: NEXT I 
1@8 PRINT: PRINT 

11@ PRINT “MULTIPLICATION TABLES MOD ” ™ 
128 GOSUB 88@ 

138 FOR 1=@ TO M-1 

14@ PRINT Is" "3 

15@ FOR J=@ TO M-1 

168 PRINT FNB(I,d,™)3 

176 NEXT J: PRINT: NEXT I 
18@ STOP 

8@@ !ISUBROUTINE FOLLOWS: 
818 PRINT: PRINT TABC4) 3@; 
828 FOR I=1 TO M-1 

83@ PRINT I3s NEXT Is PRINT 
84@ FOR I=] TO 2*M+3 

852 PRINT "-"s: NEXT Is: PRINT 
862 RETURN 

876 END 


Figure 3-1 


Modulus Arithmetic 


RUNNH 


ADDITION AND MULTIPLICATION TABLES, MOD ™M 
GIVE ME AN M? 7 


ADDITION TABLES MOD 7 


AN—AU LS 
bane au 
Ub aN aan 


8 1! 2@ 3 4 5 6 


@ 886 @ @ 6 B 
1 @t 2 3 4 5 6 
2 82 4 6 1 3 5 
3 @ 3 6 25 1 4 
4 @ 41 5 2 6 3 
5 @5 3 1 6 4 2 
6 @ 6 5 43 2 1 
STOP AT LINE 188 
READY 


Figure 3-1 (Cont.) 


Modulus Arithmetic 


The number of arguments with which a user-defined function is 
called must agree with the number of arguments with which it is de- 


fined. For example: 


14 DEF FNA (X) = xX*x2 + X72 
23 PRINT FNAC3s2) 


will cause an error message: 


ARGUMENTS DON'T MATCH AT LINE eo 
In a DEF statement or function reference, where a function has 


zero arguments, the function name can be written with or without 


parentheses. For example: 


1@ GEF FRA = #72 
2@ Ri = FNECs 


When calling a user-defined function, the parenthesized arguments 
can be any legal expressions. The value of each expression is sub- 


stituted for the corresponding function variable. For example: 


16 DEF FNZ¢ko=RTS 
26 LET Aze2 
S@ PRINT FR2ce+hs 


line 30 causes 16 to be printed. 


If the same function name is defined more than once, an error 


message is printed. 


10 DEF FNMEX: 
2GDEF FNKCKD=N+H 
ILLEGAL FN REGEFINITION AT LINE Ze 


The function variable need not appear in the function expression 


as shown below: 


1@ DEF FNA €X%) = 4 +2 
ea LET R = FNAC1@)+1 
39 PRINT H 
4e@ END 
RUNNY 

7 


The program in Figure 3., contains examples of a multi-variable 


DEF statement in lines 10, 25, and 40. 
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3.8 SUBROUTINES 

When a particular mathematical expression is evaluated several 
times throughout a program, the DEF statement enables the user to 
write that expression only once. The technique of looping allows the 
program to do a sequence of instructions a specified number of times. 
If the program should require that a sequence of instructions be ex- 
ecuted several times in the course of the program, this is also 


possible. 


A subroutine is a section of code performing some operation re- 
quired at more than one point in the program. Sometimes a compli- 
cated I/O operation for a volume of data, a mathematical evaluation 
which is too complex for a user-defined function, or any number of 


other processes may be best performed in a subroutine. 


More than one subroutine can be used in a single program, in 
which case they can be placed one after another at the end of the 
program (in line number sequence). A useful practice is to assign 
distinctive line numbers to subroutines; for example, if the main 
program uses line numbers up to 199, use 200 and 300 as the first 


numbers of two subroutines. 


LISTNH 

1 REM - THIS PROGRAM ILLUSTRATES GOSUB ANB RETURN 
1@ DEF FNAC(X)= ABSCINT(X)) 

28 INPUT A,B,C 

36 GOSUB 108 

48 LET A=FNACA) 

58 LET B=FNA(B) 

68 LET C=FNACC) 


72 PRINT 
8@ GOSUB 186 
$8 STOP 


192 REM - THIS SUBROUTINE PRINTS OUT THE SOLUTIONS 

118 REM - OF THE EQUATION: AXT2 + BX + C = @ 

128 PRINT “THE EQUATION IS “ A “HXtT2 +" BO™HRK +" C 
130 LET D=BxB - 4*A*C 

140 IF D<>@ THEN 172 

‘5@ PRINT “ONLY ONE SOLUTION... x “3 -B/(2*A) 

168 RETURN 

178 IF D<@ THEN 290 

188 PRINT "TWO SOLUTIONS...X ="3 

185 PRINT (-B+SQR(D))/(2*A)s "AND X ="3 (-B-SQR(D))/(2#A) 
19@ RETURN 

290 PRINT “IMAGINARY SOLUTIONS... X = ("3 

285 PRINT ~B/(2*A) ”,” SQR(-D)/(2*A) ") AND ("3 

287 PRINT -B/(2*A) ","3 -SQR(-D)/(2*A) ")" 

218 RETURN 

996 END 
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RUNNH 

? L,e5,729 

THE EQUATION IS 1 *XT2 + 4.5 *X + °,5 
TWO SOLUTIONS...X = .5 AND X =el 


THE EQUATION IS 1 *XxtT2 + O@ *X + 1 
IMAGINARY SOLUTIONS... X = ( @, 1) AND (€ @ ,-1 ) 
STOP AT LINE 98 


READY 


Lines 100 through 210 constitute the subroutine. ‘The subroutine 
is executed from line 30 and again from line 80. When control returns 
to line 90 the program encounters the STOP statement 
execution. 


3.8.1 GOSUB Statement 

Subroutines are usually placed physically at the end of a program 
before DATA statements, if any, and always before the END statement. 
The program begins execution and continues until it encounters a GOSUB 


statement of the form: 
line number GOSUB <line number> 


where the line number following the word GOSUB is the first line num- 
ber of the subroutine. Control then transfers to that line in the 


subroutine. For example: 


56 GOSUB 229 


Control is transferred to line 298 in the user program. The first 


line in the subroutine can be a remark or any executable statement. 


3.8.2 RETURN Statement 

Having reached the line containing a GOSUB statement, control 
transfers to the line indicated after GOSUB; the subroutine is proc- 
essed until the computer encounters a RETURN statement of the form: 


line number RETURN 


which causes control to return to the statement following the orig- 
inal GOSUB statement. A subroutine is always exited via a RETURN 


statement. 


Before transferring to the subroutine, BASIC internally records 
the next sequential statement to be processed after the GOSUB state- 
ment; the RETURN statement is a signal to transfer control to this 
statement. In this way, no matter how many subroutines or how many 


times they are called, BASIC always knows where to go next. 
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3.8.3 Nesting Subroutines 
Subroutines can be nested; that is, one subroutine can call 


another subroutine. If the execution of a subroutine encounters a 
RETURN statement, it returns control to the line following the GOSUB 
which called that subroutine. Therefore, a subroutine can call 
another subroutine, even itself. Subroutines can be entered at any 
point and can have more than one RETURN statement. It is possible 
to transfer to the beginning or any part of a subroutine; multiple 


entry points and RETURNs make a subroutine more versatile. 


The maximum level of GOSUB nesting is dependent on the size of 
the user program and the amount of core storage available at the 


installation. Exceeding this limit results in the message: 


MAXIMUM CORE SIZE EXCEEDED AT LINE xxx 


where xxx is the line number of the line containing the error. 


3.9 STOP AND END STATEMENTS 

The STOP and END statements are used to terminate program execu- 
tion. The END statement is the last statement in a BASIC program. 
The STOP statement can occur several times throughout a single pro- 
gram with conditional jumps determining the actual end of the program. 


The END statement is of the form: 
line number END 


The line number of the END statement should be the largest line num- 
ber in the program, since any lines having line numbers greater than 
that of the END statement are not executed and are not retrieved 


by the OLD command (although they are saved with the SAVE command). 


NOTE 


A program will execute without an END statement; 
however, an error message is printed if a pro- 
gram is recalled having been saved without an 
END statement. 

The STOP statement is of the form: 


line number STOP 
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and causes: 


STOP AT LINE line number 
READY 


to be printed when executed. A CONTINUE command entered at this point 
resumes execution at the statement following STOP. 


Execution of a STOP or END statement causes the message: 


to be printed by the teleprinter. This signals that the execution of 
a program has been terminated or completed, and BASIC is able to ac- 
cept further input. The execution of an END statement also closes 
all files in a BASIC program. 
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PART II 


~ BASIC-PLUS ADVANCED FEATURES 


This part of the manual describes the special features of BASIC- 
PLUS which make the language a superior tool for all manner ‘of data, 
manipulation. Additional capabilities of the statements previously 
described are included, along with new. statements, character string 
manipulating facilities, integer mode variables and arithmetic, and 
intrinsic Matrix functions. Also described is the immediate mode of 
operation weten. causes _ BASIC to treat single statements as commands . 


In general, the new techniques presented here allow. thé user to 
write programs, which conserve core space and» reduce » execution time. 
With the ability to manipulate character strings, - Bie neer can. write 


a ae aa programs ‘to handle a wide Senge “of data. 


2 ‘nine deen fuaeceene allow the user to perform matrix: I/O and 
the matrix operations of addition, subtraction, multiplication, 


inversion and transposition. 


It 


CHAPTER 4 


IMMEDIATE MODE OPERATIONS 


4.1 USE OF IMMEDIATE MODE FOR STATEMENT EXECUTION 

It is not necessary to write a complete program to use BASIC-PLUS. 
Most of the statements discussed in this manual can either be included 
in a program for later execution or be given on-line as commands, which 
are immediately executed by the BASIC processor. This latter facility 
permits the RSTS-11 user to have an extremely powerful desk calculator 


available whenever he is on-line. 


BASIC-PLUS distinguishes between lines entered for later execution 
and those entered for immediate execution solely on the presence (or 
absence) of a line number. Statements which begin with line numbers 
are stored; statements without line numbers are executed immediately 


upon being entered to the system. Thus the line: 
10 PFINT "THIS IS A PDR-11" 


produces no action at the console upon entry, while the statement: 


PEINT "THIS If A -DP-11" 
THIS IS A PDF-11 


READY 


when entered causes the immediate output shown above. The READY mes- 


sage is then printed to indicate the system readiness for further in- 


4.2 PROGRAM DEBUGGING 

Immediate mode operation is especially useful in two areas: pro- 
gram debugging and the performance of simple calculations in situations 
which do not occur with sufficient frequency or with sufficient com- 


plications to justify writing a program. 


In order to facilitate debugging a program, the user can 
place STOP statements liberally throughout the program. Each STOP 
statement causes the program to halt, printing the line number at which 
the STOP occurred; at which time the user can examine various data 


values, perhaps change them in immediate mode, and then give the 


CONT 


command to continue program execution. However, a syntax error in 
immediate mode or one of several other conditions could prevent 


continuation of program execution with the CONT command. 


When using immediate mode, nearly all the standard statements 


can be used to generate or print results. 


The user can also halt program execution at any time by typing 
CTRL/C. Immediate mode can then be used to examine and/or change 
data values. Typing the CONT command resumes program execution. 


Whenever execution cannot be continued, the message: 
CAN'T CONTINUE 
READY 


is printed upon entering the CONT command. 
4.3 MULTIPLE STATEMENTS PER LINE 


Multiple statements cannot be used on a single line in immediate 


mode. For example: 


A=1: PRINT A 
ILLEGAL IN IMMEDIATE MODE 


READY 


The use of the FOR modifier (and all other modifiers described 
in Section 8.7) is allowed. Thus a table of square roots can be 


produced as follows: 


PRINT I, SQRC(I) FOR I=1 TO 1@ 
l 


1.41421 
1.73285 
2 
2.23687 
2.44949 
2.64575 
2.82843 
3 

g 3.16228 


—K—ODNQAIAMRWNH 


READY 


4.4 RESTRICTIONS ON IMMEDIATE MODE 


Certain commands make no logical sense when used in immediate 
mode. Commands in this category include: 
DEF 
FNEND 
DIM 
DATA 


FOR 
NEXT 


When any of these is given, the message ILLEGAL IN IMMEDIATE MODE is 
printed. 


4.5 PROGRAM INTERRUPTION BY CTRL/C 


eee the AMDT /O amen tne tine 
ig the CTRL/C combination, 


the integer variable LINE contains the line number of the statement 
being executed when the interrupt occurred, The PRINT command is 
used to display the contents of LINE. 

4C 


READY 
PRINT LINE 


399 
READY 


5.1 CHARACTER STRINGS 


CHAPTER 5 


CHARACTER STRINGS 


The previous chapters describe the manipulation of numerical in- 


formation; however, BASIC also processes information in the form of 


character strings. 


ters treated as a unit. 


A string, in this context, is a sequence of charac- 


A string can be composed of any combination 
of the characters in Table 5-2. 


Without realizing it, the reader has already encountered character 


strings. 


month, given its number: 


Consider the following program which prints the name of a 


“TYPE A NUMBER BETWEEN 1 AND 12"5N 


N<l OR N>12 THEN PRINT “NUMBER OUT OF RANGE™SUOTO 194 


LISTNH 

16 INPUT 

15 IF 

20 IF N>3 THEN 
25 IF N=1 THEN 
30 IF N=e@ THEN 
35 IF N=3 THEN 
40 IF N=4 THEN 
45 IF N=5 THEN 
56 IF N=6 THEN 
55 IF N=7 THEN 
66 IF N=8 THEN 
65 IF N=9 THEN 
70 «IF Ne 

75 IF 

80 IF 

85 END 

READY 

RUNNH 


PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 


"THE" N “TH MONTH IS "3 

“THE FIRST MONTH IS JANUJARY" 
“THE SECOND MONTH IS FEBRUARY" 
"THE THIRD MONTH IS MARCH" 
"APRIL" 

‘may 

a JUNE" 

"JULY" 

"AUGUST" 

"SEPTEMBER" 


104 THEN PRINT "OCTOBER" 
N=1i THEN PRINT 
N=12 THEN PRINT 


"NOVEMBER" 
"DECEMBER" 


TYPE A NUMBER BETWEEN 1 AND 12? 9 
THE 9 TH MONTH IS SEPTEMBER 


READY 


In Chapter 3 the INPUT and PRINT statements were shown printing 


messages along with the input and output of numeric values (see lines 
10 and 15 above). 


These messages consist of character string constants 
(just as 4 is a numeric constant). 


In a similar way, there are char- 
acter string variables and functions. 


5.1.1 String Constants 


Just as numbers can be used as constants or referenced by vari- 


able names, BASIC-PLUS allows for character string constants. 


Charac- 
ter string constants are delimited by either single or double quotes. 
For example: 


195 LET Y$ = "FILE4" 
33 BlS = 'CAN' 
88 IF A$ = "YES" GOTO 25% 


where "FILE4", 'CAN' and "YES" are character string constants. 


5.1.2 Character String Variables 


Variable names can be introduced for simple strings and for both 
lists and matrices composed of strings (which is to say one and two 
dimensional string matrices). Any legal name followed by a dollar 
sign ($) character is a legal name for a string variable. For example: 
AS 
c7$ 


are simple string variables. Any list or matrix variable name fol- 


lowed by the $ character denotes the string form of that variable. 
For example: 


VS (N) M2$ (N) 
CS (M,N) G1$ (M,N) 


(where M and N indicate the position of that element of the matrix 
within the whole) are list and matrix string variables. 


The same name can be used as a numeric variable and as a string 
variable in the same program with the restriction that a one anda 
two dimensional matrix cannot have the same name in the same program. 


For example: 


A A(N) 
AS AS (M,N) 


can all be used in the same program, but 


(MON 
qa 


A{N} and A ,N)} 


cannot. Likewise, 
AS(N) and AS (M,N) 
cannot both occur in the same program. 


Just aS numeric variables are automatically initialized to @ when a 
program is run, string variables are initialized to a null string 
containing zero characters (the character string constant ""). 


5.1.3 Subscripted String Variables 


String lists and matrices are defined with the DIM statement, as 


are numerical lists and matrices. For example: 
146 DIM S$15¢5) 


indicates the S$1$ is a string matrix with six elements, S1$(@) through 
$18(5), which can be separately accessed. If a DIM statement is not 
used, a subscripted string variable is assumed to have a dimension of 
10 (11 elements including the zero element) in each direction. Note 
that the dimension of a string matrix specifies the number of strings 
and not the number of characters in any one string. For example, if 


the first statements in a program are: 


10 FOR I=1 TO 7 
29 LET BSCI)="PDP-11" 
30 NEXT I 


they would cause a list BS$(n) to be created having 11 accessible ele- 
ments, B$(@) through B$({1f). The elements B$(1) through B$(7) are set 
equal to "PDP-11" and the others would be null strings (have no char- 
acters). As a general rule, all lists and matrices should be dimen- 


sioned to the maximum size being referenced in the program. 


5.1.4 String Size 


A character string can contain any number of characters limited 
only by the amount of core storage available. However, the 
LINE FEED key cannot be used to type a string on two or more terminal 
lines. Since core storage is limited, strings can also be saved in 


files on the system disk (see Section 9.6.2). 


5.15 Relational Operators 


When applied to string operands, the relational operators indi- 


cate alphabetic sequence. For example: 
55 IF ABCI) < ASCI+1) GOTO 199 


When line 55 is executed the following occurs: AS(I) and AS(I+1) are 
compared; if A$(I) occurs earlier in alphabetical order than AS(I+1l), 
execution continues at line 100. Table 5-1 contains a list of the 


relational operators and their string interpretations. 


Table 5-1 


Relational Operators Used With 
String Variables 


The strings A$ and BS are equivalent. 


The string A$ occurs before BS$ in alpha- 
betical sequence. 


The string A$ is equivalent to or occurs 
before BS in alphabetical sequence. 


The string AS occurs after BS in alpha- 
betical sequence. 


The string A$ is equivalent to or occurs 
after B$ in alphabetical sequence. 


The strings AS and B$ are not equivalent. 


The strings A$ and B$ are identical. 
This operator is not available 
prior to Version 5B (RSTS/E) 
systems. 


In any string comparison (except ==), trailing blanks are ignored. 
That is to say "YES" is equivalent to "YES ", Where two strings of un- 
equal length are compared, the shorter is padded with trailing blanks 
to the length of the longer string. A null string (of length zero) is 
considered to be completely blank and is less than any string of length 
greater than zero unless that string consists of all blanks in which 


case the two strings are equivalent. 


Individual characters in a string can be referenced through use 
of the CHANGE statement. The CHANGE statement permits the user pro- 
gram to transform (the entirety of) a character string into a list of 
numeric values or a list of numeric values into a character string. 
Each character in a string can be converted to its ASCII equivalent 
or vice versa. Table 5-2 describes the relationship between the ASCII 


characters and their numerical values. 


As an illustration, consider the following: 


LISTNH 

10 DIM X(3) 

15 LET A$ = “CAT” 

2@ CHANGE A$ TO x 

25 PRINT X(®)$X(1) $X (2) sx (3) 
32 END 


READY 


RUNNH 
3 67 65 84 


READY 


X(1) through X(3) take on the ASCII values of the characters in the 
string variable A$. The first element of Xx, X (2), becomes the number 
of characters present in A$. If more characters are present in the 
string variable than can be accommodated in the numeric list, the 
message SUBSCRIPT OUT OF RANGE is printed. The first element of 

the list becomes the number of characters in the string which have 
been successfully transformed into numeric values, and is less than 
or equal to the dimension of the list. Notice that line 10, above, 
created a 4-element array, X. A DIM statement must be used in this 
instance; otherwise, the system creates a default 121l-element array, 


leading to possible illogical results. 


Table 5-2 


ASCII Character Codes 


ASCII 
Decimal Char- RSTS 
Value acter Usage 


ASCII 
Decimal Char- RSTS 
Value acter Usage 


ASCII 
Decimal Char- RSTS 
Value acter 


g FILL character 86 Vv 
1 SOH 87 WwW 
2 STX 88 Xx 
3 ETX CTRL/C . 89 Y 
4 EOT / 9g Z 
5 ENQ g 91 [ 
6 ACK 1 92 \ 
7 BEL BELL 2 93 j 
8 BS 51 3 94 “or + 
9 HT HORIZONTAL TAB 52 4 95 — Or + 
1g LF LINE FEED 53 5 96 * Grave accent 
11 VT VERTICAL TAB 54 6 97 a 
12 FF FORM FEED 55 7 98 b 
CARRIAGE RETURN 56 8 99 c 
57 9 1998 a 
CTRL/O : 11 e 
; 192 £ 
< 193 g 
= 194 h 
> 195 i 
? 196 j 
@ 197 k 
A 198 1 
B 199 ™m 
Cc 11¢ n 
D 111 ° 
CTRL/Z 69 E 112 p 
ESCAPE! 72 F 113 q 
71 G 114 xr 
72 H 115 s 
73 I 116 t 
74 a 117 u 
75 K 118 Vv 
76 L 119 w 
77 M 129 x 
78 N 121 y 
79 ie) 122 Zz 
ap P 123 { 
81 Q 124 | Vertical Line 
82 R 125 } 
83 Ss 126 ~ Pilde 
84 Bu DEL RUBOUT 
42 85 U 
lALTMODE (ASCII 125) or PREFIX (ASCII 126) keys which appear on some terminals are 
translated internally into ESCAPE. 


NOTE 


The decimal values 128 through 255 can appear in character strings. For most 
practical purposes, the characters represented by N and N+128 (decimal) are the 
same. However, the characters CHR$(N) and CHRS(N+128) do not test as equal if com- 
pared. Users should be careful when performing output of these values since they may 
have some significance in certain device-dependent operations (see Chapter 12). 
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Another program which transforms a character string into a list 


of numeric values is shown below: 


LISTNH 
1@ DIM AC(65) 
15 READ A$ 


2@ CHANGE A$ TO A 

25 FOR I=8 TO AC(@) 

32 PRINT ACI) s:NEXT I 

35 DATA ABCDEFGHI JKLMNOPQRSTUVWXYZ 
48 END 


READY 
RUNNH 
26 65 66 67 68 69 78 T1 72 


82 83 €4 85 86 87 88 89 94 
READY 


Notice that A(f) = 26. 


73 


74 


15 


76 


77 


78 


79 88 81 


To change numbers into string characters, CHANGE is used as 


follows: 


LISTNH 

12 FOR 1:8 To 5 

15 READ ACI) 

20 NEXT J 

25 DATA 5,65,66,67,68,69 
30 CHANGE A TO ag 


55 PRINT A 
ERD? AS 


READY 


RUNNH 
ABCDE 


READY 


This program prints ABCDE because the numbers 65 through 69 are 
the code numbers for A through E. 


Before CHANGE is used in the matrix-to-string direction, the pro- 
grammer must indicate the number of characters in the string as the 
zero element of the matrix. In line 15 of the previous program, A(Q) 
is read as 5. The following is another example of a numeric list to 


character string conversion: 


LISTNH 

1@ DIM V(128) 

15 INPUT "HOW MANY CHARACTERS” 3V(@) 
28 FOR I=1 TO V¢(@) 

25 INPUT VC(I) 

3@ NEXT I 

35 CHANGE V TO A$ 

42 PRINT A$ 

52 END 


READY 


RUNNH 

HOW MANY CHARACTERS? 3 
? 67 

? 64 

? &7 

Cew 

READY 

Numbers which have no character equivalent in Table 5-2 do not 


cause a character to be printed. 


5.3 STRING INPUT 
The READ, DATA and INPUT statements can be used to input string 
variables to a program. For example: 


18 READ A$, B, C, D 
2@ DATA 17, 14, 13.4, CAT 


causes the following assignments to be made: 


AS = the character string "17" 
B = 14 
c = 13.4 


reading D as CAT causes the message ILLEGAL NUMBER AT LINE 19 
to be printed. 

Quotation marks are necessary around string items in DATA state- 
ments only when the string contains a comma, or when leading, trail- 
ing or embedded blanks within the string are significant, or when 
lower case letters are to be preserved. Quotes (single or double) 
are always acceptable around string items, even though not always 
necessary. For example, the items in line 40 in the following pro- 
gram are all acceptable character strings and would be read as printed. 
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LISTNH 

18 READ A$,BS$,C$,D$,E$ 

26 PRINT A$;B$3C$3D$3E$ 

3@ PRINT A$,BS,C$,D$,E$ 

48 DATA “MR. JONES",MISS SMITH, "MRS. BROWN”, "MISS", ‘"MR*° 


READY 

RUNNH 

MRe JONESMISSSMITHMRS, BROWNMISS" MR” 

MR. JONES MISSSMITH MRS. BROWN MISS "MR" 
READY 


A READ statement can appear anywhere in a multiple statement line, 

but a DATA statement must be the last statement on a line. See also 
the MAT READ statement which reads matrices (either numeric or string), 
Section 7.2. 


NOTE 


The data pool composed of values from the 
programmed DATA statements is stored in- 
ternally as an ASCII string list. Where 

a numeric variable is read, the appropriate 
ASCII to numeric conversions are performed. 
Where a string variable is read, the string 
is used as it appears in the DATA statement. 
If the item did not appear in quotes, lead- 
ing, trailing and embedded spaces are ig- 
nored. If the item did appear in quotes, 
the string variable is equated to the en- 
tire string within the quotes. 


The INPUT statement is used to input character strings exactly 
as though accepting numeric values. For example: 
16 INPUT "YOUR NAME") N#i "SOUR AGE": A 
is functionally equivalent to: 


28 PRINT "YOUR NAME"; 
45 INPUT RE 

46 PRINT “YOUR AGE"; 
42 INPUT A 


Another feature of the INPUT statement when used with character 
string input is the INPUT LINE statement of the form: 


line number INPUT LINE <string vartable> 


For example: 


1@ INFUT LINE A 


which causes the program to accept a line of input from the terminal 
with embedded spaces, punctuation characters, or quotes. Any charac- 
ters are acceptable in a line being input to the program in this man- 
ner. The program can then treat the line as a whole or in smaller seg- 
ments as explained in Section 5.5 which describes string functions. 


No text string can be output with the INPUT LINE statement, this 
facility is only available in the INPUT statement. For example: 


1@ INPUT LINE "TRAT"s AF 
SYNTAS ERROR AT LINE 18 


An INPUT LINE statement reads the entire line as typed by the 
user, including the line terminating character. The line terminator 
is one of the following: 


a. Carriage return/line feed, generated by typing the 
RETURN key (appends the ASCII values 13 and 1 to 
the character string); 


b. Line feed, generated by typing the LINE FEED key 
(appends the ASCII values 1f, 13 and § to the char- 
acter string); or 


c. ESCAPE, generated by typing the ESCAPE, ALT MODE 
or PREFIX key, depending upon the terminal (appends 
an ASCII 27 to the character string). 


5.4 STRING OUTPUT 


When character string constants are included in PRINT statements, 
only those characters within quotes are printed. No leading or trail- 
ing spaces are added. For example: 


LISTNH 

LQ 852. Gee. 91: Ag="AS" 
20 PRINT Ags" Be" 4 

2 PRINT "DONE" 

46 END 


READY 
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RUNNH 
A= 2 b= 2.64 
DOME 


READY 


Semicolons separating character string constants from other list items 
are optional. For example, in line 20 (above) note that the variable 
Y is not separated from the character string " B=" by a semicolon. 


Character string output can also contain the string functions de- 
scribed in Section 5.5. 


5.5 STRING FUNCTIONS 


Like the intrinsic mathematical functions (e.g., SIN, LOG), BASIC-~ 
PLUS contains various functions for use with character strings. These 
functions allow the program to concatenate two strings, access part of 
a string, determine the number of characters in a string, generate a 
character string corresponding to a given number or vice versa, search 
for a substring within a larger string, and perform other useful opera- 
tions. (These functions are particularly useful when dealing with 
whole lines of alphanumeric information input by an INPUT LINE state- 
Ment.) The various functions available are summarized in Table 5-3. 


5.5.1 User-Defined String Functions 


Character string functions can be written in the same way as 
numeric functions. (See Sections 3.7.3 and 8.1.) The function is 
indicated as being a string function by the $ character after the 
function name. 


User-defined string functions return character string values, 
although both numeric and string values can be used as arguments to 
the function. For example, the following multiple-line function (see 
Section 8.1) returns the string which comes first in alphabetical 


order: 


19 DEF FNFSCASsBS) 
20 FNFS=AS 


39 IF AS>BS THEN FNFS=R$ 
40 FNEND 


The following function combines two strings into one string: 


196 DEF FNCSCXSs YS) =KS+YS 


Numbers cannot be used as arguments in a function where strings 


are expected or vice versa. Line 80 is unacceptable: 


10 DEF FNASCA€) = CHRSCLENCAS$)41) 
60 LET Z=FNA$C4) 


The message: 


ARGUMENTS DON'T MATCH AT LINE 84 


is printed. 


The following code is a string function which returns the leftmost 


five characters from the sum of three arguments: 


LISTNH 

75 DEF FNASCXsYsZ7) = LEFT CNUMSCX+Y+Z)25) 
84 PRINT FNA$(10432%53) 

READY 


RUNNH 
123 


READY 


NUMS$ (123) is a five-character string, as follows: 


" (space) 123 (space) " 


Table 5-3 


String Functions} 


Indicates a substring of the string AS from the first 
character through the nth character (the leftmost N 
characters of the string A$). For example: 


PRINT LEFTCAS 72%) 
ABCDEFG 


Function Code 


LEFT (AS ,N3%) 


Indicates a substring of the string AS from the yth 
character through the last character in A$ (the right- 
most characters of the string A$ starting with the 

nth character). For example: 


RIGHT (AS ,N$%) 


PRINT RIGHT(CASs20z%) 
TUVWXYZ 


MID (AS,N1%,N2%) Indicates a substring of the string A$ starting with 
character Nl, and N2 characters long (the characters 
between and including the Nl through N1+N2-1 characters 
of the string A$). For example: 


PRINT MIDCASs15%552) 
OPARS 


Indicates the number of characters in the string A$ 
(including trailing blanks). For example: 


PRINT LENCAS) 
26 


Indicates a concatenation operation on two strings. 
For example "ABC"+"DEF" is equivalent to "ABCDEF". 
"12"4+"34"+"56" is equivalent to "123456". 


CHRS (N$%) Generates a one-character string having the ASCII 
value of N (see Table 5-2). For example: CHRS$(65) is 
equivalent to "A". Only one character can be generated. 


ASCII (AS) Generates the ASCII value of the first character in 
AS. For example, ASCII("X") is equivalent to 88, the 
ASCII equivalent of X. If BS = "XAB", then ASCII(B$) 


= 88. 


DATES (N%) where N=, this function returns the current date in 
the form: 


12-Aug-72 


This quantity can be printed on output by simple ref- 
erence to the function. It should be noted that dates 
are output using both upper and lower case letters. 
When the output device is not capable of generating 
lower case letters, the ASCII values still imply 

lower case. Where N#@, the function translates N into 
a date string. (See Section 8.8.) 


laS in the immediate mode examples is assumed to be: 
"ABCDEFGHIJKLMNOPQRSTUVWXYZ". 


Table 5-3 (Cont.) 


String Functions 


INSTR(N1%,A$,BS$) Indicates a search for the substring B$ within 
the string A$ beginning at character position 
Nl. Returns a value of 9 if BS is not in AS, 
and the character position if B$ is found to be 
in A$ (character position is measured from the 
Start of the string with the first character 
counted as character 1). For example: 


PRINT INSTR(5%5A5s"O0P") 
i5 


If B$ is a null string (B$ = ""), the INSTR 
function returns the value 1. The null string 
is a proper substring of any string and is 
treated conventionally as the first element of 
A$ in null string search operations. In addi- 
tion, if both A$ and B$ are null strings, the 
INSTR function returns the value 1 


SPACES (N$%) Indicates a string of N spaces, used to insert 
spaces within a character string. 


NUMS (N) Indicates a string of numeric characters 
representing the value of N as it would be 


output by a PRINT statement. NUMS$(n)=(space)n 
(space) if n>g and NUMS(n)=-n(space) if n<f@. 
For example: 


PRINT NUMS(1-99)"A" 
1A 


Computes the numeric value of the string of 
numeric characters A$ (may include digits, +, 
-, . and E). If AS contains any characters not 
acceptable as numeric input with the INPUT 
statement, an error results. For example: 


PRINT VALC'1.5E1") 
15 


TIMES (N) Where N=, this function returns the current 
time-of-day as a string of the form: 


1:30 PM 


where N<>g, the function translates N into a 
time string (See section 8.8). If the 


system was generated using the 24-hour time 
option, 1:30 PM is returned as 13:30. 


Table 5-3 (Cont.) 


String Functions 


Creates a string of length Nl and characters 
whose ASCII decimal value is N2. For example, 
to create a string Y$ composed of 10 space 
(blank) characters CHR$ (32%), execute the 

following statement: 


Function Code 


STRINGS (N1,N2) 


Y$ = STRINGS(18,532) 


See Table 5-2 for the decimal values of ASCII 
characters. 


CVTSS (SS$,M%) Converts the source character string 
S$ according to the decimal value of 
the integer M%. For a complete explana- 


tion of this function, see Section 12.5. 


CHAPTER 6 


INTEGER AND FLOATING POINT OPERATIONS 


Numbers on the system can be represented and manipulated in either 
integer or floating point format as described in Section 2.5.1. The 
implications of representing numbers in a certain format and the 
resuitant benefits are described in this chapter. Certain operations 
involving integer numbers are more efficient if performed using a 
forced one-word integer format. The specification of a forced integer 
format and the possible integer operations are described in Section 
6.1 through 6.6. The results of performing operations by mixing the 
formats are described in Section 6.7. Operations using standard 
floating point arithmetic and floating point scaled arithmetic are 
performed as described in Section 6.8. 


6.1 INTEGER CONSTANTS AND VARIABLES 


Normally, all numeric values (variables and constants) specified 
in a BASIC program are stored internally as floating-point numbers. 
If operations to be performed deal with integer numbers, significant 
economies in storage space can be achieved by use of the integer data 
type (which uses only one computer word per value). Integer arithmetic 
is also significantly faster than floating-point arithmetic. Integer 
variables (and constants) can assume values in the range -32768 to +32767. 


A constant, variable or function can be specified as an integer 
by terminating its name with the % character. For example: 


100% As FNX3 (Y) 
-4% Al$% FNL (N%,L%) 


The user is expected to indicate where an integer constant is to be 
generated by using the % character. Otherwise a floating-point value 


is normally produced. 


When a floating-point value is assigned to an integer variable, 
the fractional portion of that number is lost. The number is not 
rounded to the nearest integer value. (A FIX function is performed 
rather than an INT function.) For example: 


causes A% to be assigned the value -l. 
6.2 INTEGER ARITHMETIC 


Arithmetic performed with integer variables is performed modulo 
2+16. The number range -32,768 to +32,767 is treated as continuous, 
with the number after +32,767 equal to -32,768. Thus, 32767% + 2% = 
-32767% and so on. 


Integer division forces truncation of any remainder; for example 
5%/7%=0 and 199%/100%=1. Operations can be performed in which both 
integer and floating-point data are freely mixed. The result is 


stored in the format indicated as the resulting variable, for example: 
25 LET XZ = NZ + FNACK)*2 


The result of the expression on the right is truncated to provide an 
integer value for X%. The result of mixing integer and floating-point 
data is explained in Section 6.7. 


Where program size is critical, the use of the % character to 
generate integer values is encouraged as it uses significantly less 
storage space. For example: 


10 FOR I%=1% TO 107 
takes less storage space and executes faster than: 


10 FOR I=1t TO 19 


6.3 INTEGER 1/0 


Input and output of integer variables is performed in exactly the 
same manner as operations on floating-point variables. (Remember that 
in cases where a floating-point variable has an integer value it is 
automatically printed as an integer but is still stored internally as 
a floating-point number and hence takes more storage space.) It is 
illegal to provide a floating-point value for an integer variable 
through either a READ or INPUT statement. For example: 


LISTNH 

10 READ As BZ, Cs D%s E 
20 PRINT As Bas Co Dds E 
32 DATA 2675344507266 


READY 


RUNNH 
DATA FORMAT ERROR AT LINE 18 


READY 


when line 3% is changed to 
BO DATA 2074354525608 
the following is printed: 
RUNNH 
ent 5 4 5 6.8 


READY 


6.4 USER DEFINED INTEGER FUNCTIONS 


Functions can be written to handle integer variables as well as 
floating-point variables (see Sections 3.7.3 and 8.1). A function is 
defined to be of integer type by following the function name with the 
% character. 


A function to return the remainder when one integer is divided 
by another is shown below: 


19 DEF FNRZC1%Z5J%Z) = 18-J% * (14/52) 


and could be called later in a program as follows: 


100 PRINT FNRZ(A%Zs11%) 


Integer arguments can be used where floating-point arguments are 
expected and vice versa as the system performs the necessary conver- 
sions. However, strings cannot be used where numbers are required (or 
vice versa). 


75 DEF FNAZCX%Z) =X%-1% 
66 LET Z2=FNAZ(12-34) 


is acceptable. Z equals 11 after line 80 has been executed. 


6.5 USE OF INTEGERS AS LOGICAL VARIABLES 


Integer variables or integer valued expressions can be used with- 
in IF statements in any place that a logical expression can appear. 
An integer value of $% corresponds to the logical value FALSE, and 
any non-zero value is defined to be TRUE. The logical operators (AND, 
OR, NOT, XOR, IMP, EQV) operate on logical (or integer) data in a 
bitwise manner. The integer -1% (which is represented internally as 
sixteen binary ones) is normally used by the system when a TRUE value 
is required. 


Logical values generated by BASIC always have the values -1% 
(TRUE) and @% (FALSE). 


The following Immediate Mode sequence illustrates the use of in- 


tegers in logical applications in an IF statement: 


Deer THEN PRINT “TRUE” ELSE PRINT "FALSE" 


READY 


IF -1% AND ®2 THEN PRINT "TRUE" ELSE PRINT "FA " 
FALSE 


READY 


IF 42 AND 22 THEN PRINT “TRUE” ELSE PRINT "FALSE" 
FALSE 


READY 


tee IMP -1% THEN PRINT “TRUE” ELSE PRINT “FALSE” 
t 


READY 


Hie XOR -~1% THEN PRINT “TRUE” ELSE PRINT "FALSE" 


READY 


6.6 LOGICAL OPERATIONS ON INTEGER DATA 


BASIC-PLUS permits a user program to combine integer variables 
or integer valued expressions using a logical operator to give a 


bit-wise integer result . 


An integer value is represented internally in two's complement 
notation as a sign bit and 15 data bits. Refer to Appendix F for the 
description of the internal format of an integer. In a logical 
operation, the corresponding bits of two integer values are combined 
on a bit-by-bit basis determined by the logical operator used. The 


logical operators are defined in Section 2.5.5. 


For the purpose of logical operations, A and B as defined in the 
truth tables shown in Section 2.5.5 are modified. A becomes the 


condition of one bit in one integer value, and B becomes the condition 
of the bit in the corresponding bit position of another integer value. 
The truth tables are as follows. 


A NoT A 
1 | g 
g 1 


The result of a logical operation is an integer value generated 


by combining the corresponding bits of two integer values according 
to the rules shown in the truth tables above. For example, the 
following command prints the logical product of the integers 85 and 
28. 


PRINT 8S% AND 28% 
22 


READY 


Each bit in the internal representation of 85% is combined with each 
corresponding bit in the internal representation of 28% according 

to the rules in the AND truth tables. By consulting the AND (logical 
product) truth table, it can be seen that a bit is generated in the 
bit position of the result only if both bits are 1 in the correspond- 
ing bit position of the integer values 85% and 28%. The resultant 
value of 29 printed by BASIC is the integer value of the bits set in 
the internal representation of the logical product. 


The following command prints the logical sum of 85% and 288%. 


PRINT 85% OR 282 
93 


READY 


From the OR (logical sum) truth table, it can be seen that a bit is 
generated in the bit position of the result if either the corres- 
ponding bit of the internal representation of 85% or 28% is al. 
The resultant value of 93 printed by BASIC is the integer value of 


the bits set in the internal representation of the logical sum. 


The result of any logical operation can be assigned to an 
integer variable. For example, the following statement assigns a 
logical product to an integer variable which, in turn, can be printed. 


LISTNH 
16 C% = 85% AND 28% 
2@ PRINT C& 


READY 


RUNNH 
2@ 


READY 


The logical operation can be used to mask a particular bit 
pattern. For example, the following BASIC-PLUS statement is used to 
generate the value of the low order eight bits, L%, of an integer 
word, W3. 


10 L% = WZ AND 255% 


The internal representation of 255% is such that the low order eight 
bits (bits @ through 7) are all 1, and the high order eight bits 
(bits 8 through 15) are all %. The AND operation (logical product) 
generates a bit in L% only if a bit appears in the corresponding bit 
position of both W% and 255%. Since 255% is known to contain all 
zeros in the high order bits and all ones in the low order bits, the 
result L% reflects the presence of bits set and cleared in the low 
order eight bits of W%. Such a use of a bit pattern is called 
masking, where the internal representation of 255% is such that it 


provides a mask to hide one portion of a bit pattern (the high order 
bits of W%) and reveals another portion of a bit pattern (the low 
order bits of W%). 


In summary, integer values can be combined as described in 
Section 6.2 using arithmetic (mathematical) operators to give arith- 
metic results. Integer values can be compared using relational 
operators (see Section 2.5.4) and can be combined using logical 
operators (see Section 2.5.5) to give either a TRUE or FALSE result 
as described in Section 3.5 or to give 0% for false or -1% for true 
as described in Section 6.5. In any case, the results of all rela- 
tional and logical operations are integer values. When a logical 
operation is performed in conjunction with arithmetic and relational 
operations, the priority scheme as described in Section 3.5 is used 
to determine the hierarchy of operations. 


Thus, with the feature described in this section, integer 
variables and integer valued expressions can be operated on by AND, 
OR, XOR, EQV, IMP and NOT to give a bit-wise integer result. 


6.7 MIXED MODE ARITHMETIC 


The user can perform arithmetic operations using a mix of integer 
and floating point numbers. To force a floating point representation 
of an integer constant, terminate it with a decimal point. Use the 3 
character as described in Section 6.1 to force an integer representa- 
tion of a constant. Constants without a decimal point or % character 
are termed ambiguous. The remainder of this section describes the 
results of arithmetic operations using a mix of numbers. 


If both operands of an arithmetic operation are either explicitly 
integer or floating point, the system generates, respectively, integer 
or floating point results. If one operand of an arithmetic operation 
is an integer and another is floating point, the system converts the 
integer to a floating point representation and generates a floating 
point result. For example, 


PRINT 12/2235 16/23 12/203 1e/2% 
@ “S§ «5 065 


READY 


In the first two operations, the system generates the explicit results; 
in the second two, the system converts the explicit integer and gener- 
ates floating point results. 


When an ambiguous constant appears in an arithmetic expression 
(for example, 10 as opposed to 10% and 10.), the system represents it 
in integer format if an integer variable (for example, I%) or an in- 
teger constant (for example, 3%) occurs anywhere to the left of the 
constant in the expression. Otherwise, the system treats the ambiguous 
constant as a floating point number. The system performs the opera- 
tion according to the rules described above. For example, 


PRINT 124/23 1/223 1/2 
@ «5 5 


READY 


In the first operation, the system treats the 2 as an integer because 
an explicit integer representation appears to the left in the expres- 
sion. In the next two operations, the system treats the ambiguous 
constants as floating point numbers since no explicit integer variable 
or constant appears to the left of the ambiguous constant in the 
expression. 
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Since the format of the results determines the results of many 
operations, the user must explicitly impose the correct format by use 
of the per cent sign or the decimal point. For example, compare the 
following calculations, assuming A(2%)=0 in each expression. 


PRINT AC22)+(€32767+2)5 AC2%) + (€32767-+2) 
-32767 32769 


READY 


The result of the first expression is guided by the appearance of the 
per cent sign and forces an integer result. The decimal point in the 
second expression forces results in floating point format. The same 
principle applies in the following example. 


PRINT 1% + 1/23 le + 1/23 1 + 172 
1 1-5 1-5 


READY 


The explicit per cent sign and the decimal point determine the format 
of the result and enables the user to control the result. 


6.8 FLOATING POINT AND SCALED ARITHMETIC 


Floating point numbers occupy either two 16-bit words or four 
16-bit words of storage in memory. With the single precision package, 
2 words are used; with the double precision package, 4 words are used. 
Appendix F describes the internal format of the two packages. 


With the 2-word format, the user can accurately represent numbers 
up to six decimal digits, and, with the 4-word format, numbers up to 
15 decimal digits. Both formats allow numbers in the range 10738 to 
10+38 approximately. An attempt to assign or compute a number outside 
the allowed range causes the FLOATING POINT ERROR condition (ERR = 48). 


The system performs output of numeric results of floating point 
calculations as described in Section 2.5.1. To perform output of 
numbers larger than six digits, the user can tailor the format as 
described in Section 10.4.1 for the PRINT USING statement. 


Since all fractional numbers cannot be represented exactly in 
binary notation, certain calculations in floating point result in an 
accumulated error. For example, the following calculation, run in 


standard four-word floating point, results in an accumulated error. 
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LISTNH 

2X = @ 

26 X = X + -G@1 FOR 12=1% TO 10808% 
30 PRINT X - 188: END 


READY 


RUNNH 
-0177636E-11 


READY 


If no accumulated error exists, the result is 0. Running the example 
code on a system using the two-word format generates a much greater 
accumulated error (approximately .00295). 


To perform decimal calculation on a system having the double pre- 
cision floating point (4-word) math package, the user can employ the 
scaled arithmetic feature to avoid accumulated error. Systems with 
two word precision do not have scaled arithmetic. The user can specify 
the number of decimal places in fractional numbers by use of the SCALE 
command. (See the description of the SCALE command in Section 2.8 of 


the RSTS-11 System User's Guide). 


With the scaled arithmetic feature, the user can select a scale 
factor between 0 and 6. The system uses the scale factor to preserve 
the accuracy of fractional numbers to that number of decimal places. 
The value 0 is a special scale factor which disables the scaled arith- 
metic feature and allows the system to perform calculations using 
standard double precision floating point arithmetic. 


With a scale factor of n between 1 and 6 in effect, the system, 
upon input of a floating point number, internally moves the decimal 
point n places to the right and rounds it to an integer. The sys- 
tem performs all subsequent calculations with the floating point 
integers and, in turn, translates the result of each arithmetic opera- 
tion into a floating point integer with the scale factor n. On output, 
the system moves the decimal point to the left n places (descales) and 
passes the result to the PRINT or PRINT USING routines to format. 


A scale factor between 1 and 6 determines the accuracy of frac- 
tional numbers. For example, with a scale factor of 2 in effect, the 
following statement, upon input, 


X = 8} 


causes the system to move the decimal point 2 places to the right. If 
any rounding is necessary, the system does it at this point. The 
system then converts the result, 1, to a floating point representation. 
Similarly, .1 becomes 10 internally; and all numbers less than .005 
become @. 


The scaled arithmetic conversion thus avoids the loss of preci- 
sion inherent in representing fractional numbers in binary notation 
since the system can represent the integer accurately in floating 
point format. This feature, therefore, allows more predictable arith- 
metic results. For example, running the following calculation with a 
scale factor of 2 yields a 0 result. 


LISTNH 

18 X = @ 

20 X = X + .@1 FOR 12=1% TO 1800% 
38 PRINT X ~ 168: END 


READY 


RUNNH 
8 


READY 


The scaling factor of 2 eliminates the inaccuracy in representing a 
fraction two places to the right of the decimal point. 


The range of integer numbers which can be represented accurately 
decreases according to the scale factor in effect. For example, with 
a scale factor of 2 in effect, two of the 15 digits must be used to 
represent the two digits of fraction. There remains 13 places to 
accurately represent the integer portion of the number. 


With a scale factor in effect, the system handles output by PRINT 
and PRINT USING statements in the standard manner. The PRINT state- 
ment still handles 6 digits or less and uses the E format for numbers 
larger than 6 digits. The PRINT USING statement formats numbers 
according to the specified string. 
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The mathematical functions described in Section 3.7 can be used 
in conjunction with the scaled arithmetic feature. With a non-zero 
scale factor in effect, the system automatically descales the number 
passed, computes the value of the function, and converts, with any 
necessary rounding, the value returned to an appropriately scaled 


floating point integer. 
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CHAPTER 7 


MATRIX MANIPULATION 


This Chapter deals with BASIC-PLUS matrix manipulation commands. Ma- 
trices canbe composed of variables of any type. A single matrix, how- 
ever, is composed of a single type of data: floating-point, integer, 
or character string. The MAT operations do not set the zero elements 
[A(f), or B(f,n) and B(n,f)] of the specified matrix to conform with 
the requested operation. 


7.1 BASIC-PLUS ARRAY STORAGE 


A BASIC-PLUS program can define the size of a matrix in one of 
two ways: explicitly, by including the matrix in a dimension state- 
ment, or implicitly, where the matrix does not appear in any dimension 
statement. Implicitly dimensioned matrices are assumed to have ten 
elements in each dimension referenced (size 10 for a one-dimensional 
matrix and size 10 by 10 for a two-dimensional matrix, with each 
dimension also having a zero row and column). Implicitly dimensioning 
the matrix A(I,J), for example, has the same effect as explicitly in- 


cluding the following statement: 
16 DIM AC165,10) 


Dimensioning a matrix (explicitly or implicitly) establishes two 
quantities for the system: the default number of elements in each 
row and column and the maximum number of elements in the matrix. 
Through use of the MAT commands, described in this Chapter, the program 
can alter the number of elements in each row and the number of columns 
in the matrix as long as the total number of elements does not exceed 
the number defined when the matrix was dimensioned. Changing the num- 
ber of elements in either or both dimensions is termed redimensioning 


the matrix. 


When a matrix is redimensioned, the user program should take 
care not to reference elements outside the currently dimensioned 
range of the matrix. For example, if the range of matrix A is 5 by 7, 
referencing A(3,8) is improper and, although no error is generated, 
generally results in some element elsewhere in the matrix being 


destroyed. 


7.2 MAT READ STATEMENT 


The MAT READ statement is used to read the value of each element 
of a matrix from DATA statements. The format of the statement is as 


follows: 
line mumber MAT READ <list of matrtces> 


Each element in the list of matrices indicates the maximum amount of 
the matrix to be read (which cannot be greater than the dimensioned 
size of the matrix). The individual elements are separated by commas. 
If the matrix name is used without a subscript, the entire matrix is 


read. For example: 


18 DIM AC2G526) 
23 MAT READ A 


The above lines read a twenty by twenty matrix of floating-point data. 
Data is read row by row; that is, the second subscript varies most 


rapidly. If line 20 had read: 


20 MAT READ AC5515) 


a five by fifteen matrix would be read and the matrix A would be re- 


dimensioned. 


7.3 MAT PRINT STATEMENT 


The MAT PRINT statement prints each element of a one or two 


dimensional matrix. The statement is of the form: 
Zine number MAT PRINT <matrix name> {33 


If the matrix name consists of an unsubscripted matrix name, the 
entire matrix is printed. If the matrix name is subscripted, then 
the subscript indicates the maximum size of the matrix to be printed 
(but does not redimension the matrix). Only one matrix can be out- 
put by a single MAT PRINT statement. 


If the matrix name is followed by a semicolon (;), the data 
values are printed in a packed fashion. If the matrix name is 
followed by a comma (,), the data values are printed across the 


line with one value per print zone. If neither character follows 


the matrix 


name (the null case), each element is printed on a 


separate line. 


19 DIM AC1Hs10)sB629.280) 

120 MAT PRINT As !'PRINT 14*10 MATRIXsPACKED FORMAT 

130 MAT PRINT BCNsM)> !PRINT N*M MATRIXs 5S ELEMENTS 
!PER LINE 


One dimensional arrays can be printed in either row or column 


format. 


MAT PRINT V 


where V is 


a singly dimensioned array, prints the array V as a 


column matrix, and 


MAT PRINT Vs; 


prints the 


array V as a row matrix, five values per line. 


MAT PRINT V3 


prints the 


array V as a row matrix, closely packed. For example: 


LISTNH 


18 
23 
34 
AA 
53 


DIM AC7)sXKC5) 

MAT READ AsX 

MAT PRINT A$:PRINT:MAT PRINT X 

DATA 213223232243355 36237951 352553754555 
EN) 


READY 


RUNNH 


al 


51 
52 
53 
54 
58 


22 23 24 35 36 37 


7.4 MAT INPUT STATEMENT 


The MAT INPUT statement is used to input the value of each 


element of 


a predimensioned matrix. The statement is of the form: 


line number MAT INPUT <list of matrices> 


Input is read from the keyboard, as with a normal INPUT statement, 

and a ? character is printed when the program is ready to accept the 
input. The LINE FEED key can be used to continue typing data on suc- 
ceeding lines. The RETURN or ESCAPE key is used to enter the data to 
the system. MAT INPUT does not affect row zero or column zero of the 


matrix. 


The MAT INPUT statement allows input of integer, floating-point 
or character string values depending upon the variable names. Where 
more than one matrix is to be input by the same MAT INPUT statements, 


the names are separated by commas. For example: 


19 DIM 42¢6289)5RBC15) 
20 MAT INPUT AZsB 


causes the program to input twenty integer elements for the array 


A% and fifteen floating-point values for the array B. 
Where an array or matrix element is specified, for example: 


290 MAT INPUT N2Z¢285) 


only 25 elements of the array are input, regardless of the number of 
elements originally specified when the array was dimensioned. The 


array is then redimensioned. For example: 


53 DIM AC29s29),34028s2) 


198 MAT INPUT AC2@s1) 
119 MAT INPUT B4sCS 


The matrix A is redimensioned in line 18%. The INPUT statement pro- 
ceeds to accept input until the entire matrix has been read or the 
RETURN or ESCAPE delimiter is encountered. Several lines can be 
input by terminating the physical keyboard line with a line feed to 
indicate continuation on the following line. 

Following the input of a matrix, the two variables NUM and NUM2 
contain the number of elements input. NUM contains the number of 
rows input or, for a one dimensional matrix, the number of elements 
entered. NUM2 contains the number of elements in the last row. For 
example, the following program inputs a variable size matrix (up to 
10x10): 


586 DIM AC10510) 

108 INPUT "TYPE MATRIX DIMENSIONS"3NsM 

116 MAT INPUT ACNsM) 

120 !CHECK TO SEE IF ENTIRE MATRIX WAS ENTERED 
134 IF NUM*kNUM2=N*M THEN 1800 

146 PRINT “YOU DIDN'T ENTER THE WHOLE MATRIX" 
154 GOTO 100 


Unlike the INPUT statement, no text string can be output with the MAT 
INPUT statement. For example: 


1049 MAT INPUT "TEXT" AZ 
SYNTAX ERROR AT LINE 199 


7.5 MATRIX INITIALIZATION STATEMENTS 


A matrix initialization statement allows the user to create ini- 
tial values for the elements of a matrix. The statement is of the 


form: 


¢(DIM1, DIM2) 5 


line number MAT <name>=<value> (DIM1) 


The name specified is the name of a predimensioned matrix, and the op- 
tional DIM1 and DIM2 specifications indicate the size of the matrix 
to be initialized. When specified, DIM1 and DIM2 cause the matrix to 


be redimensioned. The value can be one of the following: 


Value Meaning 

ZER Sets all elements of the matrix to @ (this is 
true of all matrices when they are first cre- 
ated). (Function does not set row @ or column 
g.) 

CON Sets all elements of the matrix to 1. (Function 
does not set row @ or column @.) 

IDN Sets up an identity matrix (all elements are 9g 
except for those on the diagonal, A(I,I), which 
are l). (Function does not set row @ or colum 
g.) 


If no dimensions are indicated (DIM1 and DIM2 are not specified) 
in a matrix initialization statement, the existing dimensions of the 


matrix are assumed to be unchanged. For example: 


1A DIM AC19,16)+BC15)2C0(286320) 

24 MAT A=ZER 'SETS ALL ELEMENTS OF A=6 

39 MAT B=CONC19) 'SETS FIRST 10 ELEMENTS OF Bel 
449 MAT C=IDNC19s19) 


It should be noted that these instructions do not set row zero 


or column zero, 


7.6 MATRIX CALCULATIONS 


Mathematical operators and two intrinsic functions are available 
for use with matrices. 


7.6.1 Matrix Operations 


The operations of addition, subtraction, and multiplication can 


be performed on matrices using the common BASIC mathematical symbols. 


Each of the matrix operation statements is begun with the word 
MAT and followed by the expression to be evaluated. Each of the ma- 
trices involved must be predefined in a DIM statement. The subscripts 
of the matrices need not be indicated on the statement. The matrices 
indicated for any operation must be conformable to that operation. A 
subset of one matrix cannot be indicated as part of an operation. 


4186 DIM ACS). Beets, Codes 

12@ MAT C=A+E 

RUNNH 

MATRI® DIMENSION ERROR AT LINE det 
READY 


In order for line 120 to execute properly, line 110 should read: 


118 DIM Acces. B 


LG CLS 


Multiplication of conformable matrices is indicated as follows: 


14 DIM BiG, 55,005,463, Bé16,44@) 
2@G MAT Fo = Gate 


By conformable matrices is meant that the number of columns in matrix 
D is equal to the number of rows in matrix C. The dimensions of the 
matrix R must be large enough to contain the number of columns in D 
and the number of rows in C. The operation MAT A=A*B or MAT A=B*A 


is illegal. 
Scalar multiplication of a matrix is performed as follows: 


4145 MAT C = CKo#R 


Fach element of matrix A is multiplied by the scalar value (constant, 


variable, or formula) K, indicated in parentheses. 
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The form MAT A=(K)*A is legal. Matrix A can be copied into matrix C 


(providing sufficient space is available in matrix C) as shown below: 


4124 MAT C=A 
7.6.2 Matrix Functions 


Functions exist for the performance of transposition and inver- 


sion of matrices, 
15@ WAT C=TRNCAD 
causes matrix C to be set equal to the transpose of matrix A. That 


is, C(I,J)=A(J,I) for all I,J; matrix C is redimensioned if necessary. 


For example: 


46 DIM Reais, 2559, N05, 165,05, 35 
?S MAT HeTRNON? 
458 MAT NEINVe MS 


causes N to be computed as the inverse of matrix M (M must be a square 
matrix). After the inversion is complete, the function DET is set to 
the value of the determinant of matrix M. (If the matrix being in- 
verted is sufficiently singular to make it impossible to complete the in- 
version, the message CAN'T INVERT MATRIX is printed.) The value of DET, 


then, can be used as a variable in any formula. For example: 


266 MAT A INVER: DL=SDET 
216 MAT EB INVCAS: DS=DET 
226 IF G4=1/°02 GOTO 346 ELSE FRINT “RELATIONSHIP TRUE" 


wou 


Matrix inversion, like the other BASIC-PLUS matrix operations, 
does not operate on the elements of the row # and column @ of the 
Matrix; however, inversion destroys the previous contents of these 
elements. The operation MAT A = INV(A) is legal. 


CHAPTER 8 


ADVANCED STATEMENT FEATURES 


8.1 DEF STATEMENT, MULTIPLE LINE FUNCTION DEFINITIONS 


In Chapter 3 the DEF statement is described as having the ability 
to create a one-line function which the user can call as an element in 
a BASIC statement. The user has, by now, probably felt the need for a 
user-defined function which can extend onto more than one line; such 
a facility is available. The format for a multiple-line function 


definition is as follows: 


line number DEF FN<tdenttfter><(dummy arguments )> 
<body of definitton> 


line number FNEND 


The multiple-line DEF function is distinguished from the one-line 
user functions by the absence of an equal sign following the func- 
tion name on the first line. (From zero to five arguments of any 
type or mixture of types can be used.) The value returned by the 
function is the value of FN<identifier> at the time the FNEND state- 
ment is encountered. Somewhere within the multiple-line definition 


there must be a statement of the form: 


line number {LET} FN<tdentifter> = <expresston> 


It is the value of this expression which is returned as the value of 
the function. (There may be more than one such statement, as in the 


example below.) 


The function example below determines the larger of two numbers 
and returns that number. The use of the IF-THEN statement is fre- 


quently found in multiple line functions as follows: 


14 DEF FNMC#, So 

2@ LET FAM=# 

2@ IF Ye=k THEN S& 
4@ LET FRM="' 

76 FREND 


As another example, the following is a recursive! function that com- 


putes N-factorial: 


LISTNH 

10 DEF FNFCOM2Z) 

2A IF MZ=1% THEN FNF=1 ELSE FNF=MZ#*FNFCM%Z-12%) 
33 FNEND 

35 INPUT "VALUE FOR FACTORIAL"S™ 

46 PRINT M"FACTORIAL EQUALS"FNFCM) 

5@ END 


READY 


RUNNH 
VALUE FOR FACTORIAL? 4 
4 FACTORIAL EQUALS 24 


READY 


Any variable referenced in the body of a function definition which is 
not an argument of that multiple line DEF function has its current 
value in the user program. Multiple-line DEF functions can be nested 
(one multiple-line definition can reference another multiple-line 
definition or itself). There must not be a transfer from within the 
definition to outside its boundaries or from outside the definition 
into it. The line numbers used by the definition must not be refer- 


enced elsewhere in the program. 


The parameters with which a user-defined function is called are 
strictly formal; attempts by the program to modify them are cancelled 


when the function exits to its calling program: 


LISTNH 

14 DEF FNBCX) 

26 X29: FNB=10 
39 FNEND 

49 A=1: B=FNBCA) 
59 PRINT AsB 

68 END 


READY 


RUNNH 
1 10 


READY 


‘The term recursive refers to an inherently repetitive process in which 


the result of each cycle is dependent upon the result of the previous 
cycle. 


A is not set to @ by the function FNB(A). However, any variable ref- 
erenced in the body of the function definition which is not one of the 
function arguments will retain, after exit from the function, any value 


assigned to that variable during the execution of the function. 


Functions can be written in any type and can contain any variety 


of argument types. For example: 


LISTNH 

19 DEF FNASCAsBsC&) 

28 IF A>B GOTO 44 

38 FNAS=CHRS(A+1):3 GOTO 50 

49 FNAS=CHRS$CA+CZ) 

54 FNEND 

69 INPUT "VALUES FOR AsBsCZ"3A,Bs5CH 

74 PRINT "FNAS$(AsSB,C%Z) = "FNASCAsBsCZ) 
848 END 


READY 

RUNNH 

VALUES FOR AsBsC%? 365765924 
FNAS(AsBsCZ) = < 

READY 

RUNNH 

VALUES FOR 45BsC%? 45235-6798 
FNAS(CAsBsCZ) = 5 


READY 
38.2 ON-GOTO STATEMENT 


The simple GOTO statement allows the user to unconditionally 
transfer control of the program to another line number. The ON-GOTO 
statement allows control to be transferred to one of several lines 
depending on the value of an expression at the time the statement is 


executed. The statement is of the form: 


tine number ON <expresston> GOTO <list of line numbers> 


The expression is evaluated and the integer part of the expression is 


used as an index to one of the line numbers in the list. For example: 


59 ON X¥ GOTO 196520065309 


transfers control to line number 19% if the value of X is 1, to line 
number 298 if X is 2, and to 398 if X is 3. Any other values of X 
(other than 1, 2, or 3 in this example) cause an error message to be 
printed (or a transfer to an ON ERROR-GOTO routine with ERR=58). 


8.3 ON-GOSUB STATEMENT 


The GOSUB and RETURN statements are used to allow the user to 
transfer control of his program to a subroutine and return from 
that subroutine to the normal course of program execution (see 
Section 3.8 for details). The ON-GOSUB statement is used to condi- 
tionally transfer control to one of several subroutines or to one 
of several entry points to one (or more) subroutine(s). The state- 


ment is of the form: 


line number ON <expresston> GOSUB <list of line numbers> 


Depending on the integer value (truncated if necessary) of the ex- 
pression, control is transferred to the subroutine which begins at 
one of the line numbers listed. Encountering the RETURN statement 
after control is transferred in this way allows the program to resume 
execution at the line following the ON-GOSUB line. 


An example of the statement follows: 


88 ON X-Y GOSUB 904593351914 


When line 80 is executed, the value of X-Y being either 1, 2, or 3 
causes control to transfer to line 900, 933 or 1014, respectively. 


If the quantity X-Y is not equal to l, 2 or 3, the error message:; 


ON STATEMENT OFT OF RANGE AT LINE 69 


is printed (or the user can transfer to an ON ERROR-GOTO routine with 
ERR=58). 


Since it is possible to transfer into a subroutine at different 
points, the ON-GOSUB statement could be used to determine which por- 


tion of the subroutine should be executed. 


8-4 


8.4 ON ERROR GOTO STATEMENT 


Certain errors can be detected by BASIC while executing a user 
program. These errors fall into two broad areas: computational 
errors (such as division by §) and Input/Output errors (reading an 
end-of-file code as input to an INPUT statement). Normally the 
occurrence of any of these errors causes termination of the user 


program execution and the printing of a diagnostic message. 


some applications may require the continued execution of a user 
program after an error occurs. In these situations, the user can 


execute an ON ERROR GOTO statement within his program. This state- 
ment tells BASIC that a user subroutine exists, beginning at the 
specified line number, which will analyze any I/O or computational 
error encountered in the program and possibly attempt to recover 


from that error. 


The format of the ON ERROR GOTO statement is as follows: 


line number ON ERROR GOTO {<line number>} 


This statement is placed in the program prior to any executable 
statements with which the error handling routine deals. If an error 
does occur, user program execution is interrupted and the user 

written error subroutine is started at the line number indicated. The 
variable ERR, available to the program, assumes one of the values listed 
in Table 8-l. Table 871 is also contained in Appendix C, the com- 
plete RSTS error message summary. 


When an error is encountered in a user program, BASIC checks to 
see if the program has executed the ON ERROR GOTO statement. I£f this 
is not the case, then a message is printed at the user's terminal and 
the program proceeds (if the error does not cause execution to 
terminate). If the ON ERROR-GOTO statement was executed previousiy, 
then execution continues at the specified line number where the 
program can test the variable ERR to discover precisely what error 


occurred and decide what action is to be taken. 


Table 8-1 


User Recoverable Errors 


(C) indicates that program execution continues, following printing of 


the error message, if an ON ERROR GOTO statement is not present. 


Otherwise, execution terminates and the system prints the READY mes- 


sage, 


Message Printed 


BAD DIRECTORY FOR DEVICE 


ILLEGAL FILE NAME 


ACCOUNT OR DEVICE IN USE 


NO ROOM FOR USER ON DEVICE 


CAN'T FIND FILE OR ACCOUNT 


NOT A VALID DEVICE 


I/O CHANNEL ALREADY OPEN 


DEVICE NOT AVAILABLE 


I/O CHANNEL NOT OPEN 


PROTECTION VIOLATION 


Meaning 


The directory of the device refer- 
enced is in an unreadable format, 


The filename specified is not ac- 
ceptable. It contains embedded 
blanks or unacceptable characters. 


The specified operation cannot be 
performed because the file is al- 
ready open by some user. This 
message has a general "file in use” 
meaning. 


Storage space allowed for the cur- 
rent user on the device specified 
has been used or the device as a 
whole is too full to accept further 
data. 


The file specified or current user 
account numbers were not found on 
the device specified. This message 
has a general "not there" meaning. 


Attempt to use an illegal or non- 
existent device specification 


An attempt was made to open one of 
the twelve I/O channels which had 
already been opened by the program. 


The device requested is currently 
reserved by another user. 


Attempt to perform I/O on one of the 
twelve channels which has not been 
previously opened in the program. 


The current user is not allowed to 
perform the requested operation on 
the specified file. Input may have 
been requested from an output-only 
device or vice versa. This message 
has a general "can't do that" mean- 
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Message Printed 
END OF FILE ON DEVICE 


FATAL SYSTEM I/O FAILURE 


USER DATA ERROR ON DEVICE 


DEVICE HUNG OR WRITE LOCKED 


KEYBOARD WAIT EXHAUSTED 


NAME OR ACCOUNT NOW EXISTS 


TOO MANY OPEN FILES ON UNIT 


ILLEGAL SYS() USAGE 


DISK BLOCK IS INTERLOCKED 


PACK IDS DON'T MATCH 


DISK PACK IS NOT MOUNTED 


DISK PACK IS LOCKED OUT 


ILLEGAL CLUSTER SIZE 


DISK PACK IS PRIVATE 


DISK PACK NEEDS 'CLEANING' 


Meaning 


Attempt to perform input beyond the end 
of adata file; or a BASIC source file 
is called into memory and is found 
to contain no END statement. 


An I/O error has occurred on the 
system level. The user has no 
guarantee that the last operation 
has been performed. 


One or more characters may have 
been transmitted incorrectly due 

to a parity error, bad punch com- 
bination on a card or similar error. 


User should check hardware condition 
of device requested. Possible causes 
of this error include a line printer 
out of paper or high-speed reader 
being off-line. 


Time requested by WAIT statement has 
been exhausted with no input received 
from the specified keyboard. 


An attempt was made to rename a file 
with the name of a file which already 
exists, or an attempt was made by 

the system manager to insert an ac- 
count code which is already within 
the system. 


Only one open DECtape output file 

is permitted per DECtape drive. Only 
one open file per magtape drive is 
permitted. 


Illegal use of the SYS system func- 
tion. 


The requested disk block segment is 
already in use (locked) by some other 
user. 


The identification code for the 
specified disk pack does not match 
the identification code on the pack. 


No disk pack is mounted on the speci- 
fied disk drive. 


The disk pack specified is mounted 
but temporarily disabled. 


The specified cluster size is unac- 
ceptable. 


The current user does not have ac- 
cess to the specified private disk 
pack. 


Non-fatal disk mounting error; use 
CLEAN system call. 


Message Printed Meaning 
FATAL DISK PACK MOUNT ERROR Fatal disk mounting error. 


I/O TO DETACHED KEYBOARD I/O was attempted to a hung up data- 
set or to the previous, but now de- 
tached, console keyboard for the job. 


PROGRAMMABLE ‘¢C TRAP ON ERROR-GOTO subroutine was entered 
through a program trapped CTRL/C. 


See a description of the SYS system 
function. 


CORRUPTED FILE STRUCTURE Fatal error in CLEAN system call. 


DEVICE NOT FILE STRUCTURED An attempt is made to access adevice, 
other than a disk,DECtape, or magtape 
device, as a file-structured device. 
This error occurs, for example, when 
the user attempts to gain a directory 
listing of a non-directory device. 


ILLEGAL BYTE COUNT FOR I/O The buffer size specified in the 
RECORDSIZE option of the OPEN statement 
or in the COUNT option of the PUT 
statement is not a multiple of the 
block size of the device being used 
for I/0. 


NO ROOM AVAILABLE FOR FCB When the user accesses a file under 
programmed control in RSTS-1l, a sys- 
tem control structure called an FCB 
requires one small buffer and one small 
buffer is not available for the FCB. 


UNIBUS TIMEOUT FATAL TRAP This hardware error occurs when an 
attempt is made to address nonexistent 
memory or an odd address using the 
PEEK function. An occurrence of this 
error message in any other case is 
cause for an SPR. 


RESERVED INSTRUCTION TRAP An attempt is made to execute an 
illegal or reserved instruction or an 
FPP instruction when floating point 
hardware is not available. (SPR) 


MEMORY MANAGEMENT VIOLATION This hardware error occurs when an 
illegal Monitor address is specified 
using the PEEK function. Generation 
of the error message in situations 
other than using PEEK is cause for an 
SPR. 


SP (R6) STACK OVERFLOW An attempt to extend the hardware 
stack beyond its legal size is 
encountered. (SPR) 


DISK ERROR DURING SWAP A hardware error occurs when a user's 
job is swapped into or out of memory. 
The contents of the user's job area 
are lost but the job remains logged 
into the system and is reinitialized 
to run the NONAME program. (SPR) 


ERR 


38 


39 


40 


4l 
42 


43 


44 
45 


46 


47 


48 


49 


50 


51 


52 


53 


54 


Message Printed 


MEMORY PARITY ERROR 


MAGTAPE SELECT ERROR 


MAGTAPE RECORD LENGTH 
ERROR 


NO RUN-TIME SYSTEM 


VIRTUAL BUFFER TOO LARGE 


VIRTUAL ARRAY NOT ON DISK 


MATRIX OR ARRAY TOO BIG 


VIRTUAL ARRAY NOT YET OPEN 


ILLEGAL I/O CHANNEL 


LINE TOO LONG 


FLOATING POINT ERROR 


ARGUMENT TOO LARGE IN EXP 


DATA FORMAT ERROR 


INTEGER ERROR 


ILLEGAL NUMBER 


ILLEGAL ARGUMENT IN LOG 


IMAGINARY SQUARE ROOTS 


Meaning 


A parity error was detected in the 
memory occupied by this job. 


When access to a magtape drive was 
attempted, the selected unit was 
found to be off line. 


When performing input from magtape, the 
record on magtape was found to be 
longer than the buffer designated to 
handle the record. 


Reserved. 


Virtual core buffers must be no more 
than 512 decimal bytes long. 


A non-disk device is open on the channel 


upon which the virtual array is 
referenced. 


In-core array size is too large. 


An attempt was made to use a virtual 
array before opening the corresponding 
disk file. 


Attempt was made to open a file on an 
I/O channel outside the range of the 
integer numbers 1 through 12. 


Attempt to input a line longer than 
255 characters (which includes any 
line terminator). Buffer overflows. 


Attempt to use a computed floating 
point number outside the range 
|1E-38|<n</1E38| excluding zero. If 
no transfer to an error handling 
routine is made, zero is returned as 
the floating point value. (C) 


Maximum is in the range -89<arg<+88. 
Value returned is zero. (C) 


A READ or INPUT statement detected 

data in an illegal format. For 

example, 1..2 is an improperly 

formed number, 1.3 is an improperly 
formed integer, and X" is an illegal 
string. (C). 

Attempt to use a computed integer out- 
side the range -32767<n<32767. If no 
transfer to an error handling routine 
is made, zero is returned as the 
integer value. (C) 


Integer or floating point overflow or 
underflow. 


Negative or zero argument to log func- 
tion. Value returned is the argument 
as passed to the function. (C) 


Attempt to take square root of a num- 
ber less than zero. The value returned 


is the square root of the absolute value 


of the argument. (C) 
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Message Printed 


SUBSCRIPT OUT OF RANGE Attempt to reference an array element 
beyond the number of elements created 
for the array when it was dimensioned 


CAN'T INVERT MATRIX Attempt to invert a singular matrix. 


OUT OF DATA The DATA list was exhausted and a 
READ requested additional data. 


ON STATEMENT OUT OF RANGE The index value in an ON-GOTO or 
ON-GOSUB statement is less than one 
or greater than the number of line 
numbers in the list. 


NOT ENOUGH DATA IN RECORD An INPUT statement did not find 
enough data in one line to satisfy 
all the specified variables. 


INTEGER OVERFLOW, FOR LOOP The integer index in a FOR loop 
attempted to go beyond 32766 or 
below -32766. 


DIVISION BY ¢@ Attempt by the user program to divide 
some quantity by zero. (C) If no 
transfer is made to an error hand- 
ling routine, a @ is returned as 
the result. 


8.4.1 RESUME Statement 


After the problem is corrected (if this is both possible and 
desired by the program), execution of the user program can be resumed 
through use of the RESUME statement (which is placed at the end of 
the error handling routine, much like a RETURN statement in a normal 
subroutine). The RESUME statement causes the program statement that 
originally caused the error to be reexecuted. If execution is to be 
restarted at some other point within the program (as might be the case 
for a non-correctable problem), the new line number can be specified 


in the RESUME statement at the end of the error handling routine. 


The format of tne RESUME statement is as follows: 
Line number RESUME {<Zine number>} 
For example: 


200% RESUME 
2601 RESUME 102 


The line 29@@ restarts the user program at the line in which the 


error was detected, and is equivalent to the statement: 


2000 RESUME 6 


A RESUME or RESUME § statement in an error handling routine 
passes control to the line containing the statement which caused the 
error. If the statement which caused the error is on a multiple 
statement line, control is passed to the DIM, DEF, FNEND, FOR, NEXT 
or DATA statement immediately preceding it on the line. If none of 
these six statements is present on the line, control passes to the 


first statement on the line. For example, consider the line: 


50 A=A+l : PRINT A : FOR M=1% TO 3% : INPUT X 


If an error occurs in the INPUT statement, above, control is passed 
to the preceding FOR statement on the same line - not to the first 


statement of the line. 


For this reason, a DIM, DEF, FNEND, FOR, NEXT or DATA statement 
on a multiple statement line with error handling should be the first 
statement on a line. Also, the first statement on a line should be 
the statement which may generate the trappable error. Such placement 
of the statement prevents logic errors and allows any further error 
to be handled. Any other placement of the statement causes logic 
errors because statements preceding the statement causing the error 
are executed as many times as control is passed back to the line. If 
the error handling routine must also handle errors, the program can 
pass control to a RESUME statement which, in turn, can pass control 


to the error handling routine. 


Line 2001 above restarts the user program at line 100 (which can 


be used to print some terminal message for that particular operation). 


A RESUME statement should always be included in the error handling 


routine. 


8.4.2 Disabling the User Error Handling Routine 


If there are portions of the user program in which any errors 
detected are to be processed by the system and not by the user program, 
the error subroutine can be disabled by executing the following state- 


ment: 


line number ON ERROR GOTO @ 


which returns control of error handling to the system. An equivalent 


form is: 


line number ON ERROR GOTO 


in which case line @ is assumed. Executing this statement causes the 
system to treat errors as it would if no ON ERROR GOTO had ever been 
executed. 


Generally, the error handling subroutine detects and properly 
handles only a few different errors; it is useful to have the RSTS 
system handle other errors, if they occur. For this reason, RSTS 
allows the ON ERROR GOTO @ statement to be executed within the error 
subroutine itself. Special treatment is accorded this case, in that 
the disabling occurs retroactively; the error which caused entry to 
the error subroutine is then reported and a message printed as though 
no ON ERROR GOTO statement had been in effect. 


As an example of this feature, consider an application in which 
inexperienced users interact with a BASIC program. These users may 
not know what to type at the terminal, and the program may want to 
prompt them. The program tells the system to allow up to 60 seconds 
for the user to respond (via the WAIT function, described in Section 
8.8 ) and then to alert it that the user has not replied. The program 
then prints additional information for the user. 


The program below requests the user's name with the INPUT 
statement on line 30. The ON ERROR GOTO statement is previously 
executed on line 10. 


16 ON ERROR GOTO 1669 !'SET UP ERROR ROUTINE 


24 WAITC69) WAIT 60 SEC+ FOR REPLY 
30 INPTIT "YOUR NAMES NS !GET STUDENT NAME 
5@ STOP 


* 
4 


. 


1999 !THIS IS THE ERROR HANDLING ROUTINE 

1914 IF ERR<>15 THEN ON ERROR GOTO @ !WAIT ERRORS ONLY 
1920 PRINT !SKIP TO NEW LINE 

1934 PRINT “PLEASE TYPE YOUR NAME" 

1949 PRINT “AND THEN HIT THE ‘'RETURN' KEY" 

16546 RESUME ITRY AGAIN 


In this example, if the call to the error subroutine was caused by 
some error other than the KEYBOARD WAIT EXHAUSTED error, the program 
would exit via the ON ERROR GOTO @ in line 1f1f. This permits the 
appropriate error message to be printed on the user's terminal. Note 
that exiting via the RESUME at line 1958 causes the INPUT statement to 


be restarted. 


8.4.3 The ERL Variable 


It is sometimes useful to be able to recognize the line number 
at which an error occurred. Following an error detection, the integer 


variable ERL contains the line number of the error. 


ERL would be used,. for example, to indicate which of several 
INPUT statements caused an END OF FILE error. 


Care must be taken in use of the ERL variable since changing or 
resequencing the line number field of ali or some statements within 
the program can alter the value of the ERL variable as it appears 


within an expression context. For example: 


46 ON ERROR GOTO 164 
26 INPUT "TYPE THO NON-ZERO NUMBERS"; A, & 


=@ LET H=A-CB 
q@ LET H=K+E/A 
58 PRIKT # 

6@ STOP 


100 IF ERRC?61 THEN ON ERROR GOTO 4@ 
44@ PRINT "FIRST NUMBER WAS &" IF ERL=46@ 


420 PRINT “SECOND NUMBER WAS @" IF ERLS28 


If the LET statements in lines 38 and 49 were moved to some other line 
numbers, lines 11f and 12@ would also require a change. 


8.5 IF-THEN-ELSE STATEMENT 


The IF-THEN statement allows the program to transfer control to 


another line or execute a specified statement depending upon a stated 
condition. 


The IF-THEN-ELSE statement is the same as the IF-THEN statement, 
except that rather than executing the line following the IF statement, 
another line number or statement can be specified for execution where 
the condition is not met. The statement is of the form: 


ELSE< Zine number> 


THEN<line number> 
VHUSES epavenanes } 


line number IF<econditton> THEN<statement> 
GOTO<line number> 


where the condition is defined as one of the following: 

<relattonal expresston> <logical operator> <relational expresston> 
and a relational expression is defined as: 

<expresstion> <relational operator> <expresston> 


as described in Section 3.5. The relational condition is tested; if 
it is true the THEN/GOTO part of the statement is executed. If the 
condition is false, the ELSE part of the statement is executed. Fol- 
lowing the word ELSE is either a statement to be executed or a line 


number to which control is transferred. 


As an example of an IF-THEN-ELSE statement: 
P75 IF Xo4 THEN FRINT "GREATER" ELSE FRINT “NOT GREATER" 


An IF statement can follow either the THEN or ELSE clause in the above 
statement, making it possible to nest IF statement to any desired level. 
For example: 


1@@ IF ASB THEN IF BoC THEN PRINT "AGES" 


LISINH 
16 INPUT As Rs C 
2@ IF A>R THEN 


IF B>C THEN PRINT "“A>R>c" 
ELSE IF C>A 
THEN PRINT "'C>A>B" 
FLEE PEINT “A>C>RB" 
ELSE IF A>C THEN PRINT "R>Aa>c" 
ELSE IF B>C 
THEN FRINT "B>C>Aa't 
FLSE PRINT "C>R>Aa" 


39 FND 


FFADY 


FUNNH 


2 


229921 


C>R>A 


RKRADY 


FUNNH 


2 


33 631 


R>A>C 


RRADY 


The use of the LINE FEED and TAB characters greatly improves the 


legibility of complex program statements such as line 20 above. 


The IF-THEN-ELSE statement can appear anywhere in a multiple- 


statement line. However, if this statement is followed by any other 


statements, the following rules apply: 


The physically last THEN or ELSE clause is considered to be 
followed by the next statement on the line: 


10 IF @=1 THEN 100 FLSF PRINT At PRINT "ONE" 


where A#l, the value of A and the text string ONE are printed. 


All other THEN or ELSE clauses are considered to be followed 
by the next line of the program: 


20 IF A>B THEN IF B<C THEN PRINT "B<C™: GOTO 34 
25 PEINT “A<R" 


Only in the case where "B<C" is printed is the statement 
GOTO 38 seen and executed. 


If either ASB or B>C, the line "A<B" is printed, 


8.6 CONDITIONAL TERMINATION OF FOR LOOPS 


In the simple FOR-NEXT loop described in Section 3.6.1, the for- 


mat of the FOR statement is given as: 
line number FOR<variable>=<expression>TO<expresston>{STEP<expresstion>} 


There are many situations in which the final value of the loop variable 
is not known in advance and what is really desired is to execute the 
loop as many times as necessary to satisfy some condition. In evaluat- 
ing a function, for example, this condition might be the point at which 
further iterations contribute no further accuracy to the result. 
BASIC-PLUS provides a convenient way of specifying that a loop is to 

be executed until a certain condition is detected or while some con- 


dition is true. These statements take the forms: 


relational, 


; y i ; gS . 
line numberFOR<variable>=<expresston>{STEP<expression>} WHILE pie aee on 


and 


relational, 


line numb erFOR<vart ab Le>=<expresston>{STEP<expresston>} UNTIL<) Ones sion 


The condition has the same structure as specified in an IF statement 
(see Section 3.5) and can be just as elaborate, if necessary. Before 
the loop is executed and at each loop iteration the condition is tested. 


The iteration proceeds if the result is true (FOR-WHILE) or false 
(FOR-UNTIL). 


The difference between a FOR loop specified with a WHILE or UNTIL 
and one specified with a terminal value for the loop variable is 
worth noting, in order to avoid potential pitfalls in the usage of 


each. Consider the two loops in the program below: 


LISTNH 

1@ FOR I=1 TO 14 

15 PRINT Is 

28 NEXT I 

25 PRINT "rl="J 

50 FORK I=! UNTIL 1>10 
55 PRINT I3 

60 NEXT I 

65 PRINT "I="I1 

75 END 


READY 


RUNNH 


Each of these loops prints the numbers from 1 to 10. When the loop 
at line 10 is done, however, the loop variable is set to the last 
value used (that is, 10). In the second loop beginning at line 50, 
the loop variable is set to the value which caused the loop to be 


terminated (that is, 11). 


Next consider the two loops following: 


LISINH 
19 X=10 
29 FOR I=1 TO X 
30 X=X/2: PRINT I»X 
4Q NEXT I 
50 PRINT 
60 X=10 
70 FOR 1=1 UNTIL I>xX 
80 X=X/2: PRINT IX 
90 NEXT I 
95 END 
READY 
RUNNH 
1 5 
2 2.5 
2 1.25 
4 6625 
5 23125 
é -15625 
7 +97B8125 
8 + 390625E-1 
9 -195313E-1 
10 +976563E-2 
1 5 
2 265 
READY 


In the case of the loop beginning with line 20, the iteration stops 
when I exceeds the initial value of X (that is, 10). Even though the 
value of X changes within the loop, the initial value of X determines 
the performance of the loop. In the second loop, the current value 
of X determines when the iteration ceases. Thus, after three itera- 
tions, I is greater than X in the second loop and the loop is termin- 
ated. (The STEP value when omitted, is still assumed to be 1.) 


These forms of loop control are particularly useful in iterative 
applications where data generated during the loop execution determines 


loop completion. 


Consider the problem of scanning a table of values until two 


successive elements are both 0, or the end of the table is reached: 


° 
° 


100 FOR I=1 UNTIL I=N OR XCI)=6 AND XCI+1)=0 
115 NEXT I 


The following two programs also illustrate the FOR-UNTIL and 
FOR-WHILE constructions: 


LISTNH 

10 INPUT "LETTER IS"3Y% 

eo XF=""s FOR T=1 UNTIL X#=YE OK XfS"ZZZ" 

34 READ X$: NEXT I 

46 DATA As Ps Co Ds Fs Fs GsHs Is Jo Ke La MaoNe 0s Ps Qs Re So Talo Vato Xs Ya ZaZZZ 
50 PHINT "LETTER IS NUMBER"I-1 

90 END 


READY 


RUNNH 
LETTER 1S? C 
LETTER 1S NUMBER 3 


READY 


RUNNH 
LETTER IS? @Q 
LETTER IS NUMRER 17 


READY 


19 INPUT "WORD'"3 Y$ 

28 X$=""s FOR I=1 WHILE X$<=Y$ 

30 READ X&%: NEXT I 

4@ DATA AsB> Cs Ds Es Fs Go He ls Ja Ka Lo MsNo0s Ps Os Rs Ss To Us Vo Wo Xe YsZsZZ2Z 
SO PRINT "WORD BEGINS WITH LETTER" I-2 

98 END 


REA DY 

RUNNH 

WORD? FIRST 

WORD BEGINS WITH LETTER 6 
READY 

RUNNH 

WORD? LAST 

WORD BEGINS WITH LETTER 12 


READY 


8.7 STATEMENT MODIFIERS 


To increase the flexibility and ease of expression within BASIC- 
PLUS, five statement modifiers are available (IF, UNLESS, FOR, WHILE, 
and UNTIL). These modifiers are appended to program statements to 
indicate conditional execution of the statements or the creation of 


implied FOR loops. 


8.7.1 The IF Statement Modifier 


The form: 
<statement>IF<condttton> 
is analogous to the form: 


IF<condittion>THEN<statement> 


For example: 


1@ PRINT X IF xX<>@ 
is the same as: 


1@ IF X<>@ THEN PRINT X 


The statement is executed only if the condition is true. 


When a statement modifier appears to the right of an IF-THEN 
statement, then the modifier operates only on the THEN clause or the 
ELSE clause, depending on its placement to the left or right of ELSE. 


For example: 


100 IF 151 THEN PRINT “HELLO" ELSE PRINT “BYE" IF 1=@ 


will print: 


HELLO 


Since the test 1=1 is true. The modifier IF 1=@8 is false, but 


as it applies only to the ELSE clause, it is never tested. 


It is not possible to include an ELSE clause when using the 


modifier form of IF 


Several modifiers may be used within the same statement. For 


example: 
70 PRINT XC€IsJ) IF I=J IF XCIsJ)<>@ 


prints the value of X(I,J) only if the value of X(I,J) is non-zero 
and if I equals J. When there is more than one modifier on a line, 
the modifiers are executed in a right-to-left order, That is, the 
rightmost one is executed first and the leftmost is executed last. 
This situation is described by the term "nested modifiers". 


An additional operational advantage of IF modifiers is 
illustrated in the discussion of FOR modifiers in Section 8.7.3. 


8.7.2 The UNLESS Statement Modifier 


The form: 


<statement> UNLESS <conditton> 


causes the statement to be executed only if the condition is false. 
This particular form simplifies the negation of a logical condition. 


For example, the following statements are all equivalent: 
1@ PRINT A UNLESS A=@ 
20 PRINT A IF NOT A=@6 


39 IF NOT A=9 THEN PRINT A 
4Q IF A<>@ THEN PRINT A 


Do not use the implicit GOTO statement with the UNLESS modifier; 
this may cause CATASTROPHIC ERRORS when the condition in the modifier 
are met. Instead, use the GOTO statement explicitly, as follows: 


IF A=B THEN GOTO 69% UNLESS C=D 
Do not use: 


IF A=B THEN 69% UNLESS C=D 


8.7.3 The FOR Statement Modifier 
The form: 
<statement>FOR<vari ab Le>=<expression>T0<expresston> {STEP<expresston> } 
or, the form 


WHILE<expresston>, 


<statement>FOR<vartab le>=<eapression>{STEP<eapresston} Lnmrtt <oxpression> 


can be used to imply a FOR loop on a single line. For example (using 
none of the optional elements) : 
1% PRINT Is SORCI) FOR I=1 TO 1% 
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This statement is equivalent to the following FOR-NEXT loop: 


26 FOR I=1 TO 18 
25 PRINT IsSQRC1): NEXT I 


In cases where the FOR-NEXT loop is extremely simple, the necessity 
for both a FOR and a NEXT statement is eliminated. Notice that this 
implied FOR loop will only modify (and hence execute iteratively) one 
statement in the program. Any number of implied FOR loops can be used 


in a single program. 


As in the case with all modifiers, a FOR modifier in an IF state- 
Ment operates only on the THEN or ELSE clause with which it is associ- 
ated, and never on the conditional expression to the left of the THEN. 
Thus, if it was desired to print all non-zero values in a matrix X(19@), 


the following program would not operate properly: 


1@ DIM X(160) 
15 READ XCI) FOR I=#t TO 100 
20 IF XC1)<>@ THEN PRINT I5XCI) FOR I=! TO 108 


since the implied FOR loop at line 20 applies only to the THEN PRINT... 

part of the statement, and not to the IF... part. The first value of X 

tested is X(100), since I remained at 100 from statement 15. To achieve 
the desired effect, it is only necessary to state line 20, not as an IF 

statement, but rather as a PRINT statement with nested modifiers; for 


example: 


20 PRINT I»XCI) IF XC1)<>@ FOR I=1 TO 109 


when expressed in the latter form, the nested modifier rule takes effect, 
and all the values of X(I) are tested and printed as appropriate. 


The WHILE and UNTIL clauses are explained in Section 8.6. 
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8.7.4 The WHILE Statement Modifier 
The form: 
<statement> WHILE <condittion> 


is used to repeatedly execute the statement while the specified con- 
dition is true. For example: 


19 LET X=Xt2 WHILE Xt 2<1lE6 
is equivalent to: 


10 LET X=X12 
1S IF X<1E6 THEN 10 


The WHILE modifier (and the UNTIL modifier in Section 8.7.5) operates 
usefully only in iterative loops where the logical loop structure modi- 
fies the values which determine loop termination. This is a significant 
departure from FOR loops, in which the control variable is auto- 
Matically iterated; a WHILE statement need not have a formal 

control variable. The following infinite loops never terminate: 


16 X=X+1 WHILE 1<1960 
15 PRINT IsACI) WHILE ACI)<>Q@ 


In both cases, the program fails to alter the values which are used to 
determine when the loop is done. 
A successful application of the WHILE modifier is shown below: 
§ !TEST OF SQUARE ROOT ROUTINE 
1@ X=X+1 WHILE X=SQRCXt 2) 
2@ PRINT X 


As in the UNLESS modifier case, use the GOTO statement 
explicitly to avoid an error with the WHILE modifier. 


8.7.5 The UNTIL Statement Modifier 
The form: 
<statement> UNTIL <condttton> 


is used to repeatedly execute the statement until the condition becomes 
true; which is to say, while the condition is false. For example: 


10 X=X+1 UNTIL X<>SQR¢CXt2) 


is the same as: 


19 H=e+4 
2G IF ¥=S@R“K72) THEN 16 


As in the UNLESS modifier case, use the GOTO statement 
explicitly to avoid an error with the UNTIL modifier. 


8.7.6 Multiple Statement Modifiers 


More than one modifier can be used in a single statement. Multiple 


modifiers are processed from right to left. For example: 


1@ LET A=B IF A>® IF B>@ 


which is equivalent to: 


1@ IF B>®@ THEN IF A>@ THEN A=B 


or 
1Q@ IF B>@ AND A>® THEN LET A=B 


or 
16 IF B<=@ THEN 48 
26 IF A<=@ THEN 49 
3@ LET A=B 


A two dimensional matrix (m by n) can be read one row at a time as 


follows: 


50 READ ACIs,J) FOR J=!1 TO M FOR I=1 TON 


which is equivalent to: 


56 MAT READ ACNsM) 


and to: 


59 FOR I=1 TO N 
55 FOR J=l TOM 
6 HEAD ACIsJ) 
65 NEXT J 

793 NEXT I 


Also see Section 8.7.3 which described the interaction of FOR and IF 
modifiers. 


8.8 SYSTEM FUNCTIONS AND STATEMENTS 


RSTS-11 has several system functions which allow the user to 
obtain certain information about or perform operations with the 


system, The functions are described in Table 8-2, 


Table 8-2 


SYSTEM FUNCTIONS 


DATES (9) 


DATES (N) 


TIMES (9) 


TIMES (N) 


TIME () 


TIME (1) 


TIME (2) 


TIME (3) 


TIME (4) 


returns the current day, month 
and year, in the form: 


2-Mar-72 


Note that the date contains both 
upper and lower case characters 
(where lower case is not avail- 
able on some terminals, only 
upper case letters are used but 
the ASCII values imply lower 
case). 


returns a character string cor- 
responding to a calendar date. 
The formula used to translate 
between N and the date is as 
follows: 


(day of year)+[(number of years 
since 1970) *102@) 


DATES (1) ="91-Jan~-79" 
DATES (2969) ="29-Feb-72" 


returns the current time of day 
as a character string as fol- 
lows: 


TIMES (9) ="95:39 PM" 

or"17:39 " 
returns a string corresponding 
to the time at N minutes before 
midnight, for example: 


TIMES (1)="11:59 PM" or "23:59" 
TIMES (1448)="12:98 AM" or "99:69" 
TIMES (721)="11:59 AM" or "11:59" 
N must be less than 1441 to 
return a valid string. 


returns the clock time in sec- 
onds since midnight. 


returns the central processor 
(CPU) time used for this job 
in g.1 second quanta. 


returns the connect time (time 
during which the user has been 
logged into the system) for this 
job in minutes. 


returns the number of 
kilo-core ticks (ket's) 
used by this job. 


returns the device time 
for this job in minutes. 


PRINT DATES(@) 
10-AUG~72 


READY 


155 PRINT X2C1)s DATESCI) 


75 IF TIMESC@) >= "@5345 Pm" 
THEN PRINT "TIME TO QUIT" 


PEINT TIMFS(€1) 
11:59 PM 


REA DY 


PRINT TIMESC148@) 
le:40 AM 


READY 


25 IF TIMECA)>43260 


- THEN PEINT "AFTERNOON" 


10 IF TIMEC1)>39 THEN STOP 


10 IF TIMEC2)>1@@00 THEN STOP 


8@ PRINT TIMEC3) 


4®@ IF TIMEC4)/6@>2-5 THEN 96 


Table 8-2 (Cont.) 


SWAP (1%) causes a byte swap operation to 
occur on the integer variable 
I%; returns the value of I% 
with the bytes swapped. 


Sample Usage 


18 PRINT CHRS(SWAP2Z(12%)) 


RADS (I) converts an integer to a 3- 
character string. This func- 
tion is used to convert a value 
(expression in Radix-5f@ format) 
back into ASCII. Radix-5@ is 
explained in Appendix D. 


NSU EE ee ee | 


55 PRINT RADSC(I2Z) 


There are also two special system statements that can be used 
within a BASIC-PLUS program: SLEEP and WAIT. Both statements 
allow the user to suspend his program for a stated interval. 


The SLEEP statement is of the form: 
line number SLEEP <expression> 


SLEEP is used to dismiss the currently running program for the number 
of seconds indicated by the expression. At the end of this period 
the program is again runnable. Thus, the user is guaranteed at least 
this number of seconds idle time, possibly slightly more depending 
upon the number of jobs currently active on the system. 


To awaken a job from a sleep before the specified number of 
seconds has expired, type a delimiter (RETURN, LINE FEED, FORM FEED 
or ESCAPE) at any of the job's terminals. The program segment shown 
below, however, can be used to override line terminating delimiters 
and provide a continuous SLEEP for a specified time. 

196 T=TIME (f) 

119 SLEEP T+39-TIME(Q@): 

IF TIME ()-T<3% GOTO 116 

12@ INPUT X 
In the above program, the INPUT statement is executed only if the 
time elapsed is equal to or greater than 38 seconds. Otherwise, if 
a delimiter is typed, the SLEEP is executed again for the length of 
time remaining in the original 38 seconds or until another line 
terminating character is typed. 


A job is also awakened when it has declared itself a receiver 
and a message is queued for it through the SEND/RECEIVE system 
function calls. (The SEND/RECEIVE system function calls are 


privileged and are therefore documented in the System Manager's Guide.) 
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The WAIT statement is of the form: 
line number WAIT <expresston> 


WAIT is used to set a maximum period for the system to wait for input 
from the user keyboard. If no delimiter is typed at the keyboard 
(RETURN, LINE FEED, ESCAPE) within the number of seconds specified by 
the expression, the program is restarted and a WAIT EXHAUSTED error 
occurs, which can be detected using ON ERROR-GOTO. The WAIT statement 
is used in conjunction with the INPUT statement. As an example: 


LISTNEH 

1@ ON ERROR GOTO 180 
28 WAIT 15 

38 INPUT "16 + 16 ="3A 
4@ VAIT @ 


5@ IF A=32 THEN PRINT "RIGHT!" 
ELSE PRINT "NO. TRY AGAIN": GOTO 12 
76 STOP 
1@@ IF ERR<>15 THEN ON ERROR GOTO @ 
110 PRINT "WAKE UP!" 
128 RESUME 32 
13¢@ END 


READY 


RUNNE 

16 + 16 =? VAKE UP! 
16 + 16 =? 21 

NO. TRY AGAIN 

16 + 16 =? 32 
RIGHT! 

STOP AT LINE 78 


READY 


In this example line 1f% is executed only if the user fails to 
respond within 15 seconds. The use of WAIT @ restores the terminal 
to its normal state in which no timeout occurs, but rather the 


system waits until a line is entered, however long that may take. 


PART III 


- BASIC-PLUS DATA HANDLING 


This part of he manual- contains a ‘complete description of ail 
BASIC-PLUS ‘data handling operations. Bw brief review is made of the 
_simple forms of READ, DATA, PRINT, RESTORE and INPUT along with the. 
“inexe saganwed forms of these statements. Formatted ASCII files, 


virtual core “matrices, and Record aye operations are described. 
Advanced users are. advised to consult the RsTs/E Peoqranmied < 


Manual for a discussion of savanna data handling. ‘techniques and o 


: device dapenaent operations: 


_3II 


CHAPTER 9 
DATA STORAGE CAPABILITIES 


9.1 FILE STORAGE 


Previously, techniques have been presented for entering data 
into a program as the program is written (via READ and DATA state- 
ments or from the user terminal while the program is executing (via 
the INPUT statement). Both techniques are inefficient when the amount 
of data to be read or:written increases beyond a few items. In order 
to improve operation, BASIC-PLUS provides the user with facilities to 
define and manipulate Input/Output data files. 

A BASIC-PLUS data file consists of a sequence of data items 
transmitted between a BASIC program and an external Input/Output de- 
vice. The external device can be the user terminal, some other 
terminal, disk, line printer, card reader, magnetic tape device, DEC- 
tape, or high-speed paper tape equipment. 


Each data file has both an external name by which it is known 
within the RSTS system (the name of the file on a disk storage 
device, for example) and an internal file designator (a channel num- 
ber used to reference the file). An OPEN statement (see Section 9.2) 
is used to associate an external file specification with an internal 


file channel. 


An external file specification contains some or all of the 
following information: 


device :[ proj, prog] filename. extenston<protection> 


If the device designator is not present in a file specification, the 
system device public structure is assumed. For non-file structured 
devices, only the device designator need be specified; any ftlename, 
extenston, project-programmer codes, and protection code specified 


are ignored. Refer to Table 9-l. Where a device designator appears, 


9-1 


it can be one of the following: 


Table 9-1 
Device Designations 


Device 
Designation Device 


File structured Devices? 


DF:, DK:, DP:, DB:, or SY: RSTS public disk structure as 
a whole 
SY: System disk 
DF: RF11 disk 
DK: DK7 RK11/RK@5 disk cartridge units 
8 through 7 
DP7: RP11/RP#{2/RP£3 disk pack units g 
through 7 
DB7: RP#4 disk pack units @ through 7 


DT7:? DECtape units @ through 7 


MT7:273 Industry compatible magnetic tape 
units @ through 7 
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‘ High-speed paper tape reader 


High-speed paper tape punch 
: to LP7:? Line printer units @ through 7 
? Card reader 


Current user terminal 
to KB63: Other user terminals on the 
system 
DX#: to DX7: Floppy disk units @ through 7 


IDECtape, magtape, and user disks can also be used as non-file 
structured devices. 

?Except for KB: and disks, device designation XX: is equivalent to 
XX@:. 

3MM@: to MM7: are synonyms for MT@: to MT7: when the magtape is a 
TM$2/TU16. 


For file-structured devices, each file is assigned a filename and 
extension. The filename is a string of one to six alphanumeric charac- 
ters. The filename extenston consists of a dot (.) followed by a one 
to three alphanumeric character string, usually specifying the file 
type. A null or blank extension is permitted, in which case the dot 
and filename extension field are omitted from the file designation. 
Refer to Table 9-2. The extensions recognized by the RSTS-11 system 
are as follows: 


Table 9-2 
Reserved File Extensions 


Automatically Assumed on 
Extension Significance Appended on Output Input 


. BAS indicates a BASIC-PLUS | to BASIC-PLUS source by the OLD 
source program to be programs stored with command, 
compiled; stored in a SAVE or REPLACE also assumed 
ASCII format. command. by RUN, 

CHAIN and 
UNSAVE in 
the absence 
of a .BAC 
file of the 
same name. 


indicates a compiled to BASIC-PLUS pro- by the RUN, 
BASIC-PLUS program; grams on which a CHAIN and 
stored in a binary COMPILE command is UNSAVE com- 
format, cannot be performed. mands. 
altered. 


indicates a temporary 
BASIC-PLUS file. 

These files are used 
while creating or edit- 
ing a BASIC program. 
They are deleted when 
no longer needed. 


The [proj,prog] field (containing the project and programmer numbers) 
identifies the owner of the file. If it is omitted the owner is 
assumed to be the current user. This field is meaningful only for 
disk and magtape files; it has no significance for DECtape files or 
files on non-file structured devices. The two numbers forming the 
field are decimal numbers between @ and 254, separated by a comma, and 
enclosed in square brackets or parentheses. 


NOTE 


The PDP-11 DOS/BATCH Monitor uses octal UIC 
values in the range 1,1 to 376,376. Trans- 
ferring magtape files between RSTS and DOS/ 
BATCH causes an effective decimal-to-octal 
conversion between RSTS project-programmer 
number and DOS/BATCH UIC code. RSTS DECtape 
files are assigned a [1,1] UIC code. 


Use of the $ character (dollar sign) inthe project-programmer field 
indicates that the file is stored under the system library account 
({1,2]). 


When creating a disk file (with OPEN or OPEN FOR OUTPUT, see Section 
9.2) or renaming a file (with the NAME AS statement, see Section 9.4) 
a protection field can be specified. Files can be read and/or write 
protected against three classes of users where distinctions are made 
on the basis of the project and programmer number of the user attempt~- 


ing to access the file. The three classes of users are: 


a. owner; 


b. group, all users having the same project number as the 
owner (termed the owner's group); and 


c. others, all other users not in the owner's group 


Table 9-3 is used to determine the value of the protectton code to 
achieve the desired file protection. 


Table 9-3 
Protection Codes 


read protect against owner 


write protect against owner 
read protect against owner's project 
write protect against owner's project 


read protect against all others who do not 
have owner's project number 


write protect against all others who do 
not have owner's project number 


compiled, run-only files 


privileged program 


Protection codes are stored within the system as character strings and 
consist of a decimal number within paired angle brackets. The decimal 
number is the sume of the desired combination of protection code values 
contained in Table 9-3. For example: a protection code of <48> denies 
read or write access to anyone logged into the system under an account 
number whose project number differs from the owner. The code < 48> 

is the sum of 32 (write protect against all others) and 16 (read pro- 
tect against all others). Similarly, the code <42> protects a file 
against any write operations (32=write protect against all others, 
8=write protect against other project members, and 2=write protect 
against owner, 42=32+8+2). 


The value 64 denotes a compiled file. It is added to the pro- 
tection code by the system upon compilation. A protection code of 
<124> denies read or write access to everyone but the user. It is the 
sum of 64 (compiled file), 32 and 16 (write and read protect against 
all other projects), and 8 and 4 (write and read protect against others 
in owner's project), A protection code of <104> allows all users to 
run the file only (write access is denied), because the read protect 
values, 16 and 4, do not pertain. 


The value 128 is used only with compiled files to designate a 
privileged program.’ A protection code of <232>, for example, 
denotes a privileged program which can be run but not altered by all 
users. Only privileged users can assign protection codes which include 
the value 128. 


Protection codes are normally specified only in the NAME-AS state- 
ment which allows the user to change the name and protection code of 
any file which he has previously created (see Section 9.4). However, 
protection codes can be specified as an optional part of any filename. 


For example, 


OPEN "FILE. EXT¢4@>" AS FILE 48 


The file FILE.EXT is created under the current account with a 
protection code of <4f>. 


1See the RSTS/E Programming Manual for a discussion of privilege. 


9.1.1 Auxiliary Libraries 


By specifying a certain special character, the user can designate 
an auxiliary library account on the system. This feature operates in 
a manner similar to the $ character signifying the system library 
account [1,2]. The following special characters designate the related 
auxiliary library accounts. 


Character Account 

! (CHRS (33) ) [1,3] 

% (CHRS$ (37) ) [1,4] 

& (CHRS (38) ) [1,5] 

# (CHRS$ (35) ) [proj ,$] 

@ (CHRS$ (64) ) Assignable account 


The user can refer to an account by using a character in any location 

where a project-programmer field is valid. Thus, a special character 

appearing in a file specification means that the file is stored in the 
related auxiliary library account. 


The # character is unique because the system interprets it 
according to the account under which the user is running. For 
example, if the user is running under account [19,28] and specifies 
the # character, the system interprets it to mean account [19,9]. 
This feature allows each project on the system to have its own 
library of files. 


How to assign an account to the @ character is explained in 
Section 2.7.3 of the RSTS-11 System User's Guide. 


9.1.2 Public and Private Disks 


The concept of device names for disks was introduced with little 
explanation of when a disk is to be referenced by name (e.g., DK2:) 
and when simply by default. To clarify this, the concept of public 
disks and private disks must be explained. 


A private disk is one that belongs to only a few user accounts, 
conceivably to a single user account. Files can be created under 


these accounts if the user account is one of the accounts on the disk. 
Also, files created under these accounts on a private disk can be 
read (or written) by other users only if the protection code of the 
file permits. A user who does not have an account on a private disk 


cannot create a file on it. 


A public disk, on the other hand, is a disk on which any user 
can create files. Every user has an account on a public disk as 
soon as he references it. There is always at least one public disk, 
called the “system disk", on the system. Alii public disks together 
on a system are called the "public structure" because the system 
treats all of the public disks as one unit. For example, when a 
program creates a file in the public structure, that file is placed 
on the public disk which has the most unused space. This ensures 
proper distribution of files across the disks in the public structure. 
The actual determination of which disks on a particular system are 
public and which are private is left to the system manager. There- 
fore, this allocation varies from system to system. 


Private disks are always referenced by a specific name (DK2:, for 
example). The public structure is normally referenced by default, 
although it has the specific name "SY:". The system disk is referenced 
explicitly by the name "SY@#:" and may be on any unit. Other disks on 
the system, whether public or private, are termed non-system disks. 
Referencing public disks by their specific names is not recommended: 

a file that exists elsewhere in the public structure might not be 
found or might even be deleted. The system does not allow a single 


user to store two files in the public structure under the same name. 


Private disks may be mounted and dismounted while the system is 
running. Normally, private disks are loaded only when needed, but 
public disks should be kept permanently mounted so that users can 


access all files during time sharing. 
9.2 OPEN STATEMENT 


The OPEN statement associates a file on a file-structured device 
or some non-file structured device with an I/O channel number internal 
to the BASIC program. BASIC-PLUS permits up to 12 files to be open 
at a given time, and therefore, permits internal file designators to 


be integers between 1 and 12. 


The general form of the OPEN statement is as follows: 


. p FOR INPUT . 
line number OPEN <string> [OR output! AS FILE <expression> 


One or more of the following specifications can be appended to the 


end of the statement (and are described in Sections 9.2.1 through 
9.2.4). 


[,RECORDSIZE <expresstion>] [,CLUSTERSIZE <expression>] 


[,FILESIZE <expression>] [,MODE <expression> ] 


The string field is a character string constant, variable or expres- 
sion that contains the external file specification (as described in 
Section 9.1) of the file to be opened. The AS FILE expression must 
have an integer value between 1 and 12, corresponding to the internal 
channel number on which the field is being opened. 


There are three distinct forms for the OPEN command: 


OPEN<string> FOR INPUT 
OPEN<string> FOR OUTPUT 
OPEN<string> 


The form of the OPEN statement used determines whether an 
existing file is to be opened or a new file created. 


a. An OPEN FOR INPUT statement causes a search for an 
already existing file (since the statement indicates the 
file is an input file). If no file is found, the 
CAN'T FIND FILE OR ACCOUNT error occurs. 


5@ OPEN "FILE. CAT" FOR INFUT AS FILE 4 


b. An OPEN FOR OUTPUT statement causes a search for an 
already existing file which, if found, is deleted. 
A new file is then created. 


735 OPEN “DATA. G@ic4@>" FOR GUTPUT AS FILE = 


c. An OPEN statement without an INPUT or OUTPUT designation 
attempts to perform an OPEN FOR INPUT operation as 
described above. If this fails, a new file is created. 


100 OPEN "MATR. TER" AS FILE # 


The OPEN statement does not control whether the program attempts 
to perform input or output on the disk file or whether read and/or 
write access to the file is granted’; these privileges are controlled 


by the file protection code. 


If an assignable device (all devices other than disks are avail- 
able or assignable to a single user at any given time) is referenced 
in any OPEN statement and that device is already in use by another 
user, a DEVICE NOT AVAILABLE error occurs. 


When used with disk files, an OPEN FOR INPUT or OPEN FOR OUTPUT 
allows either read or write operations on the opened file. The 
system allows write access to a file if the protection code permits 
and if no other user has write access to the file. For example, 
if user 1 opens a file, he has read and write access. When user 2 
opens the same file, he has read access only; a PROTECTION VIOLATION 
error occurs when he attempts to write on that file. When user 1 
subsequently closes the file, no user has write access until the next 
open operation. User 3 can now open the file and obtain both read 
and write access, because no other user currently has write access 
to that file. On DECtape and magnetic tape devices, the FOR INPUT 
and FOR OUTPUT clauses restrict operations on that file to the type of 
operation specified. 


NOTE 


Only one user can have write access to a 
file at a single time (unless MODE 1% is 
used, see Section 10.5.1); and user write 
access is always denied to a file with a 
-BAC extension, since compiled files can 
only be run. 


TMagtape and DECtape are exceptions to this rule, see the RSTS/E 


System Programming Manual. 


The next four sections in this manual describe the RECORDSIZE, 
CLUSTERSIZE, FILESIZE and MODE options of the OPEN statement. As 
these are sophisticated file handling tools, it is suggested that the 
novice user initially skip these sections and continue with Section 
9.2.5. 


9.2.1 RECORDSIZE Option 


When any file is opened, the system creates a buffer area in the 
user's core space to buffer all I/O to and from the file. Normally 
the amount of space reserved is determined by the device, as each 
device has a default device buffer size as described in Table 9-4. 


Table 9-4 
Default Device Buffer Size 


All disks 

Floppy disk (DXn:) 
DECtape (DTn:) 
Magtape (MTn:) 


512 characters (or bytes)! 


128 characters (or bytes) 


510 characters (or bytes)! 
512 characters (or bytes) 


High-speed reader (PR:) 128 characters (or bytes) 


High-speed punch (PP:) 128 characters (or bytes) 


Line printer (LP:) 
Card reader (CR:) 


User terminal (KB:) 


128 characters (or bytes) 


160 characters (or bytes) 


128 characters (or bytes) 


‘phe default buffer size may differ when the device is used 
as a non-file structured device. 


With the RECORDSIZE option, the user program can allocate more 
buffer space than is provided by the default case. However, in some 
cases the particular device driver may not permit additional space 
to be used. Table 9-5 shows the buffer size alterations for specific 
devices. 


Table 9-5 
Use of RECORDSIZE 


The disk drivers permit use of any 
buffer size that is an integral 
Multiple of 512 bytes. 


DECtape The DECtape driver uses only the 
first 510 bytes of the available 
buffer space (512 bytes for non-file 
structured DECtape). 


Magtape The magtape driver uses only enough 
bytes for one physical magtape 
record. 14 bytes < physical record 
< buffer size. 


High-speed reader These non-file structured devices 
High-speed punch can use any selected buffer size 
Line printer greater than the default size. 
User Terminal 


Card reader The card reader driver uses only 
enough bytes for one card's data. 


Floppy disk The floppy disk driver permits use of 
any buffer size that is an integral 
multiple of 128 bytes. 


The RECORDSIZE option has significant advantages when used with 
magtape and disk files. RECORDSIZE permits non-file structured 
access to magtape records of any length. On a disk file, total 
throughput can be improved by using a larger buffer size, as this 
permits a single disk transfer to read a large quantity of data. 
Specify only an even number of bytes in the RECORDSIZE expression. 
For example: 


19% OPEN "MASTER.DAT" FOR INPUT AS FILE 1%, RECORDSIZE 2948% 


If the file MASTER.DAT were on an RF11 disk and occupied a contiguous 
area on that disk, a 248-byte transfer would take about 33ms while 
four 512-byte transfers would take about 83ms (on the average). If 
the file did not reside in a contiguous disk area, the RSTS Monitor 
would break the 2848-byte transfer into four 512-byte transfers. 

Even in this last case, the system overhead to perform the transfer 


would be less. 
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This example raises the question of how to ensure that a file 
occupies a contiguous disk area. This can be done by means of the 
CLUSTERSIZE option described in the following Section. 


9.2.2 CLUSTERSIZE Option 


The CLUSTERSIZE option is applicable only to disk files and only 
when these files are initially created with an OPEN or OPEN FOR OUTPUT 
statement. The CLUSTERSIZE specification is ignored if this is not _ 
the case. 


The RSTS system divides each disk into a number of 256-word 
blocks. Each block is assigned a unique physical block number 
starting at 1!. Physical block numbers are assigned such that block 
n is physically contiguous with blocks n+l and n-l. 


A number of contiguous blocks taken together as a unit are called 
a cluster. RSTS permits clusters to be 1, 2, 4, 8, 16, 32, 64, 128 
or 256 blocks long. When the disk is initialized (the process by 
which the disk is cleared for use on RSTS) a minimum cluster size 
can be established. This minimum cluster size (also called the pack 
cluster size) can be 1, 2, 4, 8, or 16 blocks. 


For each file on the system, an entry is made in the owner's file 
directory (User File Directory or UFD) containing the filename, cluster 
size for the file, and a sequential list of blocks belonging to that 
file. 


A UFD has a fixed maximum size which is determined when the UFD 
is created?. A UFD on any one disk cannot exceed 112 (decimal) blocks 
(28,672 words). If all files were a minimum size (7 or fewer clusters 
long) a UFD clustered as 16 would have room for a maximum of 1157 
files. To keep the list of blocks belonging to the file as short as 
possible, the UFD contains a one-word entry for the first block of 
each cluster. Knowing the first block number of the cluster and the 
number of blocks in the cluster is sufficient to determine all of the 
blocks in the cluster. 


‘Block @ of each disk is reserved for a bootstrap record and is not 
used by any file. 


2The maximum size of a UFD is seven times the cluster size for 

that UFD, which is established when the account is created, and may 
be 1, 2, 4, 8 or 16 blocks. The figures given in the text assume 

a UFD cluster of 16. 
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Because of the size limit on the UFD, large files benefit from 
the specification of large cluster sizes. In an extreme example, the 
UFD would be completely filled by a single file of 24,283 blocks where 
the file cluster size is one block. However, with a cluster size of 
256 blocks, only 128 words of the UFD are required to describe this 
file. 


Since most user files are not extremely large, omitting the 
CLUSTERSIZE option when creating the file makes little practical 
difference. Omitting the CLUSTERSIZE option has the effect of assign- 
ing a cluster size equal to the pack cluster size for the disk on 
which the file resides. 


Once a file is opened on an internal I/O channel, all I/O re- 
quests by the BASIC program are handled by means of a read or write 
call from BASIC-PLUS to the Monitor, directed to the nth logical 
block of the file. The RSTS system translates the logical block 
number into a physical block number. This is done by reading the list 
of physical clusters belonging to the file (as kept in the UFD) and 
finding the entry corresponding to the nth logical block. To minimize 
the overhead involved in reading the UFD, which is stored on the disk, 
part of this list of clusters belonging to a file is kept in memory. 
This part of the list is called the file window. The file window is 
composed of seven entries from the list of file clusters. Since each 
entry corresponds to one cluster of the file, with a file cluster size 
of one block, 7 blocks (or 1792 words) of the file are described by 
the in-core file window. These 7 blocks can then be read or written 
without accessing the complete list from the UFD stored on the disk. 
Similarly, with a file cluster size of 256 blocks, the file window 
describes the location of 1792 blocks of the file, or over 459,969 
words. When performing random access I/O to virtual core arrays and 
RECORD I/O files, any of the 1792 blocks would be read or written 
without referencing the UFD. 


As an example of the use of the CLUSTERSIZE option: 


1@6 OPEN "MAT. CAT" FOR GUTPUT AS FILE tn, CLUSTERSIZE tet 


In this case the file MAT.DAT is created with a cluster size of 128 
blocks. Note that the file is initially 128 blocks long and is ex- 
tended as needed in 128-block increments. 


Since files with large cluster sizes must be extended by a whole 
cluster at a time and since clusters are always contiguous blocks, 
it may not always be possible to find sufficient contiguous free 
blocks to extend the file. The user should be aware of this possi- 
bility whenever he creates a file with a cluster size larger than the 
pack cluster size (the minimum cluster size for that disk). 


As another example (typing LINE FEED following FILE 1%,): 


18@ OPEN "DATA" FOR QUTFUT AS FILE de, 
RECORDSIZE 26462, CLUSTERSIZE 4h 


The RECORDSIZE option improves disk throughput when multiple blocks 
can be read or written in a single transfer (see Section 9.2.1). 

By creating the file with a cluster size of 4 (1924 words or 2948 
characters per cluster) the user guarantees that logical blocks 1-4, 
5-8, etc., of his file are physically contiguous on the disk. 


9.2.3 FILESIZE Option 
A disk file (and only a disk file) can be pre-extended by using 
the FILESIZE option in an OPEN statement, eliminating the need for a 
PUT statement. The format for the FILESIZE option is: 
[Zine number]OPEN <string>[FOR OUTPUT] AS FILE<expr>[,FILESIZE <expr>] 
For example: 
169 OPEN "“WALUES" FOR GUTPUT AS FILE Se. FILESIZE Sax 


The data file, VALUES is opened and automatically pre-extended 
to 50 256-word blocks. 
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9.2.4 MODE Option 


The OPEN statement allows another option: the MODE field. The 
format of the OPEN statement, including the MODE field, is as follows: 


FOR INPUT 


[Zine number] OPEN <string> [EOR ouTPuT! 


AS FILE <expr> 


{,RECORDSIZE <expr>] [,CLUSTERSIZE <expr>] [,MODE <expr>] 


The MODE option is used to establish device-dependent properties of 
the file. MODE §% is assumed by the system when MODE is omitted. 
For disk files, MODE indicates that the file is to be updated or 
appended (see Section 10.5). For non-file structured magtape opera- 
tions, MODE establishes the density and parity settings for magtape. 
For line printer operations, MODE is used in conjunction with the 
optional forms control to establish the current form length. For 

card reader operation, MODE sets a read mode to correspond to specific 
data card formats. 


9.2.5 File Structured Vs. Non-File Structured Devices 


RSTS/E distinguishes between file structured (disk, DECtape and 
magtape) devices and non-file structured devices. When a file is to 
be found or created on a file structured device, the file specifica- 
tion string in the OPEN statement must include both a device desig- 
nation (or default public structure) and a filename. On non-file 
structured devices, the device name alone identifies a file (filename 
and extension, if specified, are ignored). For example: 


DTg: is insufficient information to specify a file. 

DT@:FRED is sufficient to specify the file FRED on 
DECtape unit @. 

PP: uniquely specifies the high-speed punch. 

PP: FILE specifies a file on the high-speed punch, 


the filename is ignored. 


DX1: uniquely specifies floppy disk unit 1: 


File specification syntax is such that the default device (the public 


disk storage area) need not be specified. For example: 


SY:QUIZ 


is equivalent to: 


QUIZ 


It is also possible to open a file structured device in non-file 
structured mode. For example: 


OPEN "DKe:" AS FILE Sea 


is sufficient to open a disk cartridge in non-file structured mode. 


9.3 CLOSE STATEMENT 


The CLOSE statement is used to terminate I/O between the BASIC 
program and a peripheral device. Once a file has been closed, it 
can be reopened for reading or writing on any internal file designator. 


All files must be closed before the end of program execution. 
Execution of a CHAIN statement automatically closes any open files, 
but does not cause the output of the last blocks to output files. 
The format of the CLOSE statement is as follows. 


line number CLOSE <expresston> [,<expression>...] 


The expression indicated has the same value as the expression in the 
OPEN statement and indicates the internal channel number of the file 
to close. Any number of files can be closed with a single CLOSE 
statement; if more than one file is to be closed, the expressions 


are separated by commas. For example: 


255 CLOSE 2, 
345 CLOSE 16 


Line 255 above closes the files opened on internal I/O channels 2 
and 4. Line 345 closes the file open on internal I/O channel 10. 


9.4 NAME-AS STATEMENT, FILE PROTECTION AND RENAMING 


The NAME-AS statement is used to rename and/or assign protection 
codes to a disk or DECtape file, and can only be used on a given 
file by someone logged into the system under the account number which 
owns the file. The format of the statement is as follows: 


line number NAME<string>AS<string> 


The specified file (the first string indicated) is renamed (as the 
second string indicated). When the file resides on a device other 
than the default device (system disk), the device must be specified 
in the first string and may optionally be specified in the second 
string. No filename extension assumptions are made by NAME-AS; the 
filename extension must be specified in both strings if any extension 
is present in the old filename or desired in the new filename. 

For example: 


?S NAME "“OTG:0LD. BAS" AS “NEW. BAS” 


is equivalent to: 
YS NAME "DT@- OLD. BAS" AS "DTS: NEW. BAS" 
but the statement: 


96 NAME "FILEL. BAS" AS "FILES" 


is not advised since FILE2 has no extension and could not subsequently 
be called into core via the OLD or RUN commands (which require file- 


name extensions). 


A file protection code can be specified within typed angle 
brackets as part of the second <string> although it is not required. 
If a new file protection code is specified, it is reflected in the 
protection assigned to the renamed file. If no new protection code 
is specified, the old protection code is retained. See Section 9.1 


for a complete description of protection codes. 


406 NAME "FILE. EXT" AS "FILE. EXTC4e>" 


changes only the protection code of the file FILE.EXT stored on the 
system disk. 


2@0 NAME “DTG: ABC. BAS" AS “Arte BAS" 


changes the name of the file ABC.BAS on DECtape unit @. Since no 
transfer of the file from one device to another can be performed with 
the NAME-AS statement, it is not necessary to mention DTf: twice; 
that is, the device of the new filename need not be specified. How- 
ever, an error is generated if a device other than the old device is 
specified. 


420 NAME "NEW" AS “NEWL" 


changes only the name of the disk file NEW. (To transfer a file 
between devices, use the PIP system program described in the RSTS-11l 


System User's Guide.) 


9.5 KILL STATEMENT 
The KILL statement is of the form: 
| tine vunber| KILL <string> 


and causes the file named string to be deleted from the user's file 
area. (The file can no longer be opened, but if it is already open 
the file remains available until it is closed.) For example, when 
the user has completed all work with the file XYZ (note that the 
filename has no extension) on the system disk, he could remove the 
file from storage by executing the following statement: 


455 KILL "ave" 


A user is not allowed to KILL a file that is write-protected 
against him. (He must use the NAME-AS statement to change its 
protection first.) 


The KILL (and NAME-AS) statement can be issued in immediate 
mode. It should be noted that KILL is more general than UNSAVE, which 
is primarily used to delete source (.BAS) files (see the RSTS-11 
System User's Guide). KILL can be used to delete any file, including 
a file with a null extension (which the UNSAVE command cannot delete). 


9.6 CHAIN STATEMENT 


If a user program is too large to be loaded into core and run in 
one operation, the user can segment the program into two or more 
separate programs. Such programs are called into core for execution 
by means of a CHAIN statement. Each program section is assigned a 
name and control can be transferred between any two programs. A 
CHAIN statement is of the form: 


and causes the program named by the string to be called, compiled (if 
necessary), and executed. The line number, if specified, designates 
the line at which the program is to be started. If the Zine number 
is omitted, the program is started at the lowest numbered line (as 
though a RUN command had been used). The CHAIN statement is the last 
statement executed in each program segment other than the last seg- 


ment. For example: 


1868 CHAIN "MAIN. BAC" 2606 


causes the program MAIN.BAC to be loaded and started at line 29%. 
Notice that a filename extension is not required. The compiled 
form of the program is searched for and, if found, run. If the 
compiled form is not found, the non-compiled form is searched for 
and, if found, compiled and run. If neither form of the program is 


found, an error occurs. 


On the other hand, if a filename extension is specified, and 
not found, an error occurs; in this case, no other form of the pro- 


gram is searched for. 


Chaining to precompiled program files (.BAC files) is con- 
siderably more efficient that chaining to BASIC source program files 
since .BAS files require compilation upon each call. 


Communication between chained programs is performed by means 
of user's files or core common. 


When the CHAIN statement is executed, all open files for the 
current program are closed, the new program segment is loaded, and 
execution continues. Any files to be used in common by several 


programs should be opened in each program. 


The CHAIN statement also implicitly closes all open I/O 
channels, which is slightly different from the actions performed as 
a result of a CLOSE statement. For example, the line printer drivers 
perform two top of form operations when the printer is closed with a 
CLOSE statement. To continue printing on the same piece of paper, 
do not execute a CLOSE statement on the line printer channel; the 
CHAIN statement is sufficient to close the printer without per- 
forming top of form operations, 


Similarly, an explicit close of the paper tape reader clears 
the input buffers and prepares for a new tape. The implicit close 
performed by the CHAIN statement does not clear the buffers and the 
program subsequently chained may resume where the previous program 
stopped. An explicit close of the paper tape punch causes a trailer 
to be punched; the implicit close does not. 


CHAPTER 10 


BASIC-PLUS INPUT AND OUTPUT OPERATIONS 
10.1 READ AND DATA STATEMENTS 


A READ statement is used to assign to a list of variables values 
obtained from a data pool composed of one or more DATA statements. 
The two statements are of the form: 


line number READ <ltst of vartables> 
line number DATA <list of values> 


The list of variables can include floating point, integer, sub- 
scripted, or character string variables. Data values must correspond 
in type with their respective variables, but the "%" character should 
not be included in integer values. Integer and floating point values 
are interchangeable, although they are stored according to the type 
of the variable. The use of quote marks is discussed below. 


The data pool consists of all DATA statements in a program. 
Values are read starting with the DATA statement having the lowest 
line number and continuing to the next higher, etc. The location of 
DATA statements in a program is irrelevant, although for simplicity 
they are usually kept together toward the end of the program. (The 
DATA statements must occur in the proper numeric sequence, however.) 
A DATA statement must be the only statement on a line, although a 
READ statement can occur anywhere on a line. Comments are not per- 
mitted at the end of a DATA statement. If a READ statement is unable 
to obtain further data from the data pool, an error message is printed 
and program execution is terminated. (This error can be treated 
through the ON ERROR GOTO statement, Section 8.4.) 


Quotes are necessary in DATA statements only around string items 
which contain a comma, when leading, trailing or embedded blanks within 
the string are significant, or when lower case letters are to be pre- 
served. The data pool, composed of values from the program's DATA 
statements, is stored internally as an ASCII string list. When a 
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numeric variable is read, the appropriate ASCII to numeric conversions 
are performed. When a string variable is read, the string is used as 
it appears in the DATA statement. If the item does not appear in 
quotes, then leading, trailing, and embedded spaces are ignored. If 
the item appears in quotes, the string variable is equated to the 
entire string within the quotes. 


Matrices are read from DATA statements via the MAT READ state- 
ment of the form: 


line number MAT READ < matrtzx> 


This reads the value of each element of a predimensioned matrix from 
the data pool. Each element in the list of matrices indicates the 
maximum dimension of the matrix to be read (which cannot be greater 
than the dimensioned size of the matrix). Individual elements are 
separated by commas. For example: 


18 DIM Atee, 26), Bose) 
28 MAT REAL A 
280 MAT READ Besa, 


The above lines read values for the 20 x 20 matrix A and 35 out of 
the possible 50 values for the B matrix (remaining elements are zero). 
Data is read row by row; that is, the second subscript varies most 
rapidly. 


10.2 RESTORE STATEMENT 

The RESTORE statement reinitializes the data pool of the program's 
DATA statements. This makes it possible to recycle through the DATA 
statements beginning with the lowest numbered DATA statement. The 
RESTORE statement is of the form: 


Line number RESTORE 


For example: 


85 RESTORE 
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causes the next READ statement following line 85 to begin reading 

data from the first DATA statement in the program, regardless of where 
the last data value was found. See Section 3.3.1 for an example 
program using the RESTORE statement. 


The RESTORE statement can be placed in any position on a multi- 
ple statement line. 


10.3 PRINT STATEMENT 
In its simplest form, the PRINT statement: 
tine number PRINT 


causes a carriage return/line feed to be performed on the user ter- 
minal. The format: 


line number PRINT <iZtst> 


causes the printing of the elements in the list on the user terminal. 
An element in the list can be any legal expression. When an element 
is not a simple variable or constant, the expression is evaluated 
before a value is printed. The list can also contain character 
strings between quotes which are printed exactly as typed between 
quotes. 


NOTE 


If a character string is enclosed ina 
PRINT statement with an initial quote 
and no terminating quote, a terminating 
quote is considered to follow the last 
character of that PRINT statement. For 
example: 


16 PRINT "NAME IS Ag 
14 PRINT "NAME IS Ae" 
2@ PRINT "NAME IS " AF 


Line 18 is shown in two equivalent forms. 
Line 28 is the correct form to generate 
the printed line: 


NAME IS JOHN COE 


where AS = "JOHN DOE". 
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Elements in the list are separated by commas or semicolons. For 
example: 


16 A=4: Bee: C 
+ 


45 PRINT A; A+E+C, C-A, "END" 


when executed causes the following line to be printed: 


1 6 z ENG 


A terminal line is considered to be divided into five’ print zones of 
fourteen spaces each. Use of these zones involves the comma character 
which causes the print head to move to the next available print zone 
(from 1 to 14 spaces away). If the fifth print zone on a line is 
filled, the print head moves to the first print zone on the next 

line. 


The semicolon character functions as follows: 


a. if an integer or floating-point variable, function, 
or expression is followed by a semicolon, the value 
is printed with a preceding minus sign if the 
number is negative, or a preceding space if it is 
positive. The number is then followed by a single 
space. 


b. character strings and string variables followed by a 
semicolon are printed with no preceding or trailing 
spaces. 


Any PRINT statement which does not end with a semicolon or comma 
character causes a skip to the next line after printing the elements 
in the list. The presence of the punctuation character at the end of 
the PRINT list causes the next PRINT statement to continue on the same 
line under the conditions already defined. 


In general, the output rules for the PRINT statement are: 


a. suppression of leading zeros and trailing zeros to 
the right of a decimal point. Where a number can be 
represented as an integer, printing of the decimal 
point is also suppressed. 
™Phe actual number of print zones is INT (n/14), where n is the size 
of the print line. 
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b. at most six significant digits are printed, unless 
PRINT-USING is used. 


c. most numbers are printed in decimal format. Numbers 
too large or too small to be printed in decimal format 
are printed in exponential format. 


d. character string constants are printed without 
leading or trailing spaces. 


e. extra commas cause print zones to be skipped. 


£. semicolons separating character string constants from 
other list items are optional; omitting punctuation 
has no effect on the output format in this case. 


10.3.1 Formatted ASCII I/O 
BASIC-PLUS permits access to data files by three methods: 
a. Formatted ASCII; 
b. Virtual core arrays, described in Chapter 11; 
c. RECORD I/O, described in Chapter 12. 
Formatted ASCII data files are the simplest method of data storage, 
involving a logical extension of the PRINT and INPUT statements to 


be used in conjunction with the OPEN statement. 


The formats for INPUT and PRINT statements to be used with the 
OPEN statement are: 


line number INPUT #<expression>,<list> 


line number PRINT #<expresston>,<list> 


where the expresston has the same value as the expression in the OPEN 
statement (the internal file designator) and the Zist is a list of 
variable names, expressions, or constants as explained in the sections 
describing the PRINT and INPUT statements. 


Output can be directed to a device other than the user terminal 
with the following command: 


line number PRINT #<expresston>,<list> 


where the expression is the number of a previously opened output file, 
out of 12 possible open files (see Section 9.2). For example: 
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18 OPEN “PR: " FOR GUTFUT AS FILE 2h 
S@ PRINT #28, B. 3. 14, A+? PNR CES 


causes four values to be punched onto paper tape by the high speed 
punch which is opened for output as file 3, of 12 possible files. 
Of course, the above program segment assumes that the function FNX 


and the variables A and B are defined elsewhere in the program. 


10.3.2 Output to Non-Terminal Devices 


In order to direct output to a device other than the user terminal, 
the PRINT command is formatted as follows: 


line number PRINT #<expresston>,<list> 


where the expresston is the internal channel number (the internal file 
designator) of a previously opened output file (see Section 9.2). 

The list of information to be output can include any of the output 
information described as applicable to the PRINT statement. For 
example: 


1@ OPEN "DATRL" FOR OGUTFUT AS FILE Fe 
2@ PRINT #rfe. “STREET OF DATA FILE" 


The above lines open a file called DATA1 on the disk with internal 
channel number 7 (of 12 possible open files available in the system). 
The first line in that file reads: START OF DATA FILE. 


To output a table of square roots on the line printer, the 
following program could be used: 


LISTNH 

146 LET I¢#="LF:" 

26 OFEN I1¢ FOR GUTPUT AS FILE ih 

3@ PRINT #12, I.5@R¢13 FOR lai TO Sk 
46 END 

READY 

RUNNH 

READY 
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The result would appear on the line printer as follows: 


1 4 

2 4.4424 
2 1.72265 
4 z 

i] 2. 22687 


10.3.3 PRINT-USING Statement 


In order to perform formatted output, the following statement 
is used: 


line number PRINT[#<expression>,]USING <string>, <list> 


where the expression (which is optional) indicates the internal channel 
number of the file or device which is the destination of the output; 
the string is either a string constant, string variable, or string 
expression which is an exact image of the line to be printed. This 
string is called a format field. The list is a list of items to be 
printed in the format specified by the format field. All characters 
in the string are printed as they appear except for the special 
formatting characters and character combinations described on the 
following pages. The string, or portions of the string, are repeated 
until the Zist is exhausted. The string is constructed according 

to the following rules: 


Exclamation Point 


An exclamation point in the format field identifies a one charac- 
ter string field. The variable string is specified in the <list> 
within the PRINT statement. For example: 


1@ PRINT USING "!!'", "ARE". "Eb", “ERS 


which causes: 
ACE 


to be printed at the user's terminal. The first character from 
each of the three string constants or variables is printed. Any 
other characters beyond the first are ignored. 
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String Field 


A variable string field of two or more characters is indicated 
in the format field by spaces enclosed between backslashes. The 
backslash character (\) is produced by typing SHIFT/L on some keyboards. 
Enclosing no spaces indicates a field two columns wide, one space is 
equivalent to a field three columns wide, etc. For example: 


2@ PRINT USING "SSS oN", “ABCO", "EFGHI" 


causes 


REEFGH 


to be printed at the user's terminal. The first two backslashes have 
no spaces enclosed, hence permit the printing of two characters (AB). 
The second two backslashes enclose two spaces and permit the printing 
of four characters (EFGH). No spaces are printed unless specifically 
planned. 


Numeric Field 
Numeric fields are indicated with the # character in the format 


field. Any decimal point arrangement can be specified and rounding is 
performed as necessary (not truncation). For example: 


48 PRINT USING “###. ##", 42.2 


fe 
on 


causes 


to be printed on the user's terminal, while 


48 PRINT USING “####". Le. 245 
S@ PRINT USING "“#### ". 42 E45 
6@ PRINT USING "##", 164 
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causes 


12 
12. 
“ 168 


to be printed on the user's terminal. Numeric fields are right justi- 
fied; that is, if a number does not fill the allotted space, leading 
blanks precede the number. When the field specified is too small for 

a constant or variable to be printed, the % character is printed to 
indicate the error. The number is then printed without reference to the 
format field. On the other hand, when the format field specified is 
more than 20 character spaces larger than required for a constant or 
variable to be printed, a PRINT-USING BUFFER OVERFLOW non-recoverable 
error may occur. 


If the format field specifies a digit as preceding the decimal 
point, at least one digit is always output before the decimal point. 
If necessary, that digit is zero. 


Asterisks 
If a numeric field designation in the format field begins with 
**, any unused spaces in the format field are filled with asterisks. 
For example: 
49 A=2?.95: B=iGr. 5@: C=1667. oe 
26 PRINT USING “+### ##", ALE. 
prints the following: 


eae 7. 9S 
#107. 56 
1407. 5@ 


Notice that the ** characters act as two additional # characters 


as well as allowing asterisk fill. 
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Exponential format (see below) cannot be used in a field with 
leading asterisks. Negative numbers cannot be output uSing asterisk 
fill unless the sign is output following the number (see below). 


Exponential Format 


When the exponential form of a number is desired, the numeric 
format field is followed by the string ++t+ (four t characters) which 
allocates space for E-xx. Any arrangement of decimal points is per- 


mitted. For example: 


S FSH PROC O CR ERR RED 
18 A=1GG86. 
27@ PRINT USING F#., A: A 


causes 


1GE G2 16606 


to be printed at the user's terminal. 


All format positions are used to output a number with an expo- 
nent. The significant digits are left justified and the exponent is 
adjusted. 


Trailing Minus Sign 


If a numeric format field designation is terminated with a minus 
sign, the sign of the output number is printed following the number, 
rather than preceding it. A blank is printed to indicate a positive 
number. 


18 A=-18.5 
20 FRINT USING "#8. ##- #H#H. HH". FLA 


which prints: 


14.5@- ~-168. 564 
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Note that if the trailing minus is not used, space must be 
reserved in the numeric format field for the sign to precede the 
number. 


Dollar Signs 


If a numeric format field begins with $$, a dollar sign is printed 
immediately preceding the first digit of the number: 


1Q Ase? dd: Betad 85: CH2214. 46 
26 PRINT USING “*###. ##". ALE. 
which prints: 
arr. 44 
#364, 55 
# dedi. 4 (insufficient space to print C along with $ 


character) 


Note that the $$ characters provide for the printing of two additional 
characters in the number. Since one character is a $, the effect is 
to allow for one additional # designation beyond the ones typed by the 
user. 


Exponential format (see above) cannot be used in a field with 
leading dollar signs. Negative numbers cannot be output using the 
floating dollar character unless the sign is output following the 
number (see above). 


Commas 
If one or more commas appear to the left of the decimal point 
(if any) in a numeric format field, then commas are inserted every 


three digits to the left of the decimal point. A comma to the 
right of the decimal point is considered a printing character. 


For example: 


1@ PRINT USING “#, RHHRHH. HH PRE Ba. LSEdS 5,4 BE aSe. 1 
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prints the following: 


Insufficient Format 


If insufficient format characters are present in a field when a 
number is output, a % character is printed in the first position of 
the field followed by the number in standard format, usually causing 
the field to be widened to the right. The user is guaranteed his 
entire number. For example: 


14 PRINT USING “#4. #4 ## HH". Le B45, -212.5 


prints the following: 


42.35 #-42.5 


Rounding occurs when digits are dropped at the right of numbers. If 
rounding causes the number to exceed the format allowed, the % 
character is used. For example: 


14 PRINT USING “ #F #8", 125, 


wo 
wo 
oe 


prints the following: 


Format Too Large 


If a numeric format field results in an attempt to output more 
significant digits than are available for the number, zeros are 
substituted for all digits following the last significant digit. Six 
significant digits are available with the 2-word, single precision 
math package and fifteen digits with the 4-word, double precision 
math package. A PRINT-USING BUFFER OVERFLOW error may occur when a 
numeric format field results in an attempt to output more than 20 
characters before the first significant digit of the number. 
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PRINT Statement Punctuation 
When the PRINT-USING statement is used, the usual PRINT statement 
punctuation characters (commas and semicolons) have no effect on the 


output format, except that a semicolon at the end of the PRINT list 
inhibits termination of the printed line. 


1@ FRINT USING "“## ## ##". 132.5 


prints the following: 


As another example: 


14@ PRINT USING "#. #8") 2.5) 
28 PRINT "x" 


As another example: 


10 LET AeH41. 22441: Bee. 45457 

15 LET Ff = " A=He HH Eee. HE" 
209 OPEN "LP: " FOR GUTFUT AS FILE 4 
25 PRINT #4, USING Fe, ALE 


would cause: 


to be printed on the line printer. 
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10.3.4 MAT PRINT Statement 


The MAT PRINT statement allows for easy printing of a predimen- 
sioned matrix. The statement is of the form: 


line number MAT PRINT [#<expresston>, ]<matrix> 


for example: 


135 DIM Actes 
23 MAT PRINT ALdss 


If the specified matrix name is unsubscripted, the entire matrix is 
printed. If the matrix specification is subscripted, the subscript (s) 


indicates the maximum size of the matrix to be printed. 


The matrix name can be followed by a semicolon to indicate that 
the values are to be printed in a packed fashion, or by a comma to 
indicate that each element is printed in its own zone. For example: 


16 DIM AC16,16), 6616, 2@3 
26 OPEN "LP:" FOR QUTPUT AS FILE 1 


12@ MAT PRINT #4, A; ‘PRINT MATRIX A IN PACKED FORMAT 
13@ MAT PRINT #4, Et1@, 16>, '4@4#16 MATRIX IS PRINTED, 
'S VALUES PER LINE 


Row and column matrices can also be printed. For example: 


19 DIM ALS), Beias 
26 GPEN “LP:" FOR OUTPUT AS FILE 1 


3@ MAT PRINT #4. Ai ‘PRINT ON ONE LINE ON CHANNEL 4 
48 MAT PRINT #1. 6 ‘PRINT IN COLUMN FORMAT CIN 
'CHANNEL 4 


Line 38 causes A to be printed as a row matrix, closely packed; line 
49 causes B to be printed as a column matrix. The form: 


7@ MAT PRINT A, 
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would cause the matrix A to be printed as a row matrix, five values 
per line (at the user terminal). 


10.3.5 PRINT Functions 


In order to aid in formatting simple and complex PRINT statements 
the following functions are provided: 


| Function | Meaning | 


Returns the current position on the output 
line; where X is the I/O channel number. 
POS(#%) returns the value for the user's 
terminal. 


Tab to position X in the print record. For 


example, a standard terminal has 72 printable 
columns numbered @ through 71. TAB (4) causes 
sufficient spaces to be output to move the 
print head to column 4. If the print head 

is currently past position 4, no spaces are 
output. 


For example: 
1@ PRINT ""; TABC1@5; Fosca@s 


causes the following to be printed: 
# 16 


t 


9 spaces 


position 9g 


10.4 INPUT STATEMENT 


The INPUT statement allows data to be entered to a running pro- 
gram from an external device, the user's keyboard, disk, DECtape, 
paper tape reader, etc. The full form for this statement is: 


line number INPUT [#<expression>,] <variable list> 
In many cases the simpler form: 
line number INPUT <variable Llist> 


is used. This last form causes a ? to be printed at the terminal and 
the system then waits for the user to respond with the appropriate 
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values of string or numeric variables. If sufficient values are not 
typed, the system prints another ?; if too many values are typed, 
separated by commas, excess values are ignored. The user can also 
insert printed messages between the variables to be input. For 
example: 


$@ INFUT "OUR NAME [S" 7 N#, “ACCOUNT NUMBER": Ai “THANE SCL" 


when executed would allow the following interaction at the terminal 
(the underlined characters are typed by the system): 


YOUR NAME IS? CLYDE 
ACCOUNT NUMBER? S55 
THANK YOU 


ON ERROR GOTO statements can be used in a program to trap 
recoverable errors which occur during an input sequence. The errors 


shown below occur most frequently when an INPUT statement is executed. 


Error Meaning Examples 
DATA FORMAT ERROR Data input in an 3.4.5 or $2 or #16 or 
(ERR = 50) illegal form 2;3 or LORA input for 


a numeric variable; 
X" or "HELLO" "THERE" 
input for a string 


variable 
ILLEGAL NUMBER Overflow or 3E+66 or --23 
(ERR = 52) underflow 
END OF FILE ON DEVICE Input CTRL/Z 4Z 
(ERR = 11) 


The system assigns values to variables as they are input. Multi- 
ple variables can be assigned by separating them in the INPUT variable 
list by commas. Similarly, use commas or the RETURN key to separate 
values as they are input from the keyboard. For example: 


1@ INPUT &. 7, 
2@ PRINT &. %, 
RUNNH 


ha Pd 


3.44 ad 92 
READY 
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Do not use commas within a single number; the system ignores 
all characters input beyond a comma unless another variable is to be 


assigned. For example: 


Right Wrong 
10 INPUT F 1@ INPUT R 
2@ PRINT FR 20 PRINT R 
RUNNH RUNNH 
? 25,962 ? 25962 

25 25902 
READY READY 


Quotation marks (") should be used with string variables when an 
embedded comma is to be preserved. For example: 


Right Wrong 
1@ INPUT M¢# 19 INPUT MN 
26 PRINT M¢ 2G PRINT M¢ 
RUNNH RUNNH 

? "MOUSE, MICKEY" 7% MOUSE, MICKEY 
MOUSE, MICKEY MOUSE 
READY READY 


Commas can be embedded without using quotation marks via the 
INPUT LINE statement, described below. 


The format: 
Line number INPUT# <expresston>, <vartable list > 


causes input to be read from the file or device indicated in the 
expression, by the internal file designation number given when the 
file was opened. (See Section 9.2 for a description of the OPEN 
statement.) If the value of the expression is non-zero and the 
specified file is the user terminal, open as an input device, then 
no ? character is printed at the terminal when input is requested. 
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For example: 


75 OPEN "KE: " FOR INFUT AS FILE = 
66 INPUT #2, A 


The system then pauses while the user types a numeric value for the 
variable A, although no prompting ? or character string message is 
printed on the terminal. 


Another format of the INPUT statement allows the user to enter 
an entire line of data as a single character string entity, regardless 
of embedded spaces or punctuation. This is different from the nor- 
mal mode of string input, where the comma, apostrophe, single quote 
and double quote characters have special significance. The format 


is: 


line number INPUT LINE[# expression ,]<string variable> 


For example: 


25 INPUT LINE A¢ 


pauses to allow the user to enter a line followed by the RETURN, 
LINE FEED or ESCAPE key (see also Section 5.3). Every character 
input, including quotation marks and commas, is present in A$, above. 
The end of the line being input is the carriage return/line feed 
sequence (or line feed/carriage return/null or ESCAPE, see Section 
5.3) which is appended to the data typed by the user. To remove the 
CR and LF characters, use the string function LEFT, as described 

in Section 5.5. This can be done as follows: 


G$ = LEFT (GS, LEN(G$)-2%) 


END OF FILE ON DEVICE (ERR=11) occurs when CTRL/Z is input. 


As another example: 


20 OFEN "Fe. GAT" FOR INPUT AS FILE # 
25 INPUT LINE #7. BF 
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These lines cause the system to open a file F2 on the system disk 
on channel 7 (of 12 possible channels) and to read a string of 
characters up to the next LINE FEED character. (See Table 9-4 
for the size of buffers available for each device.) 


10.4.1 MAT INPUT Statement 


The MAT INPUT statement is used to input the values of a pre- 
dimensioned matrix from a specified input device. Where no device is 
specified, the input is accepted from the user terminal. For exam- 
ple: 


286 MAT INPUT Ace@s 


causes 20 floating-point values to be accepted as elements of the 
matrix A. A statement of the form:. 


line number MAT INPUT[#<expresstion>,] variable list 


causes the input to be read from a file or device previously opened 
on the internal channel indicated by the expression. 


45 DIM Bei@, 25> 
5@ OPEN “DT41:DATRIi" FOR INFUT AS FILE 1 
55 MAT INPUT #1. B18, 253 


The above lines cause the file DATAl1 on DECtape 1 to be opened for 
input on channel 1 (of 12 possible channels) and a matrix of values 
for the elements of B to be read to fill B(10,25). The zero elements 
are not assigned a value. When input is from the user terminal, ? 

is printed; however, reference to another device does not cause the 
printing of the prompting character. Depending upon the name of 

the matrix, the MAT INPUT statement allows input of floating-point, 


integer, or character string values. 


10.4.2 Input from Non-Terminal Devices 


Like the PRINT statement, the INPUT statement can operate upon 
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devices other than the user terminal. The form: 
line number INPUT #<expresston>,<ltst> 


causes input to be accepted from the previously opened file or device 
indicated in the expression (see Section 9.2). As long as the value 

of the expression is non-zero, the specified file is read through 

one of the 12 internal I/O channels. If the expression is zero, 

or missing completely, input is from the user terminal. No ? charac- 
ter is printed on the terminal when input is requested from a device 

other than the user terminal. For example: 


16 OPEN "FR:" FOR INPUT AS FILE + 
26 INPUT #3, AS. BS 


causes the strings A$ and B$ to be read from the high-speed paper 
tape reader. 


Note that the data format is identical to the standard INPUT 
format. If the user wants to read numeric or string data from a 
file previously created (on disk or DECtape, for example) he should 
insert commas and carriage returns in the data when he places the 
data in the file. For example: 


19@ OPEN "DT@:LEN" FOR QUTPUT AS FILE 41% 
116 PRINT #44, A". " B"" C 

12@ CLOSE 1: 

13@ OPEN "“DT@:LEN" AS FILE ih 

446 INPUT #44, ALEC 

15@ PRINT ALE. C 


is an acceptable sequence to print three values onto a DECtape file, 
read them from that DECtape file, and print the three values on the 
user terminal. As in the example above, once a file is opened it 

can be closed and reopened through the use of a second OPEN statement. 
Reopening the file moves the position pointer within the file back 
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to the beginning of the file, so that the entire file becomes avail- 
able again for sequential referencing. 


10.4.3 Opening the User Terminal as an I/O Channel 


The internal file designator (following the # character in the 
INPUT or PRINT statements) is always in the range 1 to 12. File 
designator # is, by definition, always open as the user's terminal. 
Internal file designator 9 cannot be closed or opened. Use of file 


## is indicated below (no OPEN #f$ statement is necessary or allowed). 


18 INPUT #6, AF 


is equivalent to: 


10 INPUT AS 


It is sometimes useful to be able to request keyboard input 
without having the "?" prompting character printed first. This can 
be accomplished by opening the user's terminal ("KB:") on some 
internal file designator other than @. The ? character is only 
generated for input requests on file #8, as shown in the following 
example: 


LISTNH 

16 OPEN "KE: " AS FILE 4 

2@ PRINT "WITH USE OF INTERNAL FILE GCESIGNATOR" 

28 PRINT “TYPE YOUR NAME, FOLLOWED BY RETURN KE" 
4@ INPUT #41, Ag; "THANE You" 

30 PRINT: FRINT 

6@ PRINT "FOR COMPARISON, WITHOUT FILE GCESIGNATOR" 
*@ PRINT "TYPE YOUR NAME, FOLLOWED BY RETURM KEY" 
S@ INPUT AS; “THANK You" 

36 END 


READY 


RUNNH 

WITH USE OF INTERNAL FILE DESIGNATOR 
TYPE YOUR NAME, FOLLOWED BY RETURN KEY 
J. oF. JONES 

THANK YOU 


FOR COMPARISON, WITHOUT FILE DESIGNATOR 
TYPE YOUR NAME. FOLLOWED BY RETURN KEY 
200. PF. JONES 

THANK You 

READY 
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10.5  APPENDING DATA TO DISK FILES 


Information can be added to existing files (appended) by using 
the MODE option, described in Section 9.2.4 in the OPEN statement. 
Once opened, a data file can be appended simply by using the 
PRINT# statement described in Section 10.3.1. 


To write data to a new block following the current end of file in 
a disk file, specify the MODE 2% option in the OPEN statement. For 
example: 


406 OPEN "DATA" AS FILE 18. MOE 22 


As a result, the system opens the file DATA under the current account 
on the system disk. The next output operation creates a new block 
and appends it to those currently allocated to the file. Any fill 
characters in the previous last block of the file remain when the 
system appends the new last block. Do not use the OPEN FOR OUTPUT 
form of the OPEN statement, as it deletes the existing file. 


10.6 PROGRAMMING EXAMPLE 


Formatted ASCII disk files can be used to store data of variable 
length. For example, strings of different sizes can be stored im- 
mediately next to each other, making the most efficient use of 


storage space on the disk. 


The example below illustrates how a programmer stores strings in 
a data file called DIARY. He opens the disk file with the MODE 2% 
option to append new data to the file when required. The program 


shown below is run the first time with the following user responses: 


1606 REM THIS FROGRAM SETS UF AN ASCII FILE IN APPEND MODE. 
1@16 CPEN "DIARY" AS FILE Sh, MODE 2 

1026 PRINT "MEST LINE": 

1@26 INFUT LINE L# 

Je4@ IF LEFTCLS., LENS L#3-25 = "END" THEN 1876 

1@5G PRINT #38, L#¥i 

1666 GOTO 1626 

1or@ CLOSE Se 

1a66 END 
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RUNNH 


NEXT LINE? JULY 5. 16g 
NEXT LINE? DEAR DIARY, 
NEXT LINE? EARLIER TODAY, WHILST REPOSING “NEATH YE CLOE APPLE TREE, 


NEXT LINE? I WITNESSED A COMMONFLACE BUT PAINFUL EVENT WHICH METHINKS MAY 
NEXT LINE? PROVE OF PUBLICK INTEREST. TO MIT: A RIPE AND GOOD-SIZED 

NEXT LINE? APPLE LOOSENED ITSELF FROM THE TREE ANC FELL ERR THNARGD, 

NEXT LINE? STRIKING THIS HUMBLE NARRATOR UPON THE HEAD ANC CAUSING HIM TO 
NEXT LINE? BE DAZED CONSIDERABLY. 

NEXT LINE? AS A RESULT, METHINKS THERE IS AN ATTRACTION BETHEEN GCDIES 
NEXT LINE? I HERE USE THE WORG ATTRACTION IN GENERAL FOR ANS ENDEAVOR 

NEXT LINE? WHATEVER, MADE BY BODIES TO APPROACH TO EACH UTHER. WHETHER THAT 
NEXT LINE? ENDEAVOR ARISE FROM THE ACTION OF THE BODIES THEMSELVES, AS 

NEXT LINE? TENDING TO EACH OTHER CR AGITATING EACH OTHER BY SPIRITS 

NEXT LINE? EMITTED; GR WHETHER IT ARISE® FROM THE ACTION GF THE ETHER OF OF 
NEXT LINE? THE AIR, OR CF ANY MEGIUM WHATEVER, WHETHER CORPOREAL GF 

NEXT LINE? INCORFOREAL, IN ANS MANNER IMPELLING BODIES PLACEG THEREIN 

NEXT LINE? TOWAROS EACH CGTHER. FURTHER, THIS ATTRACTION BETWEEN FARTICLES 
NEXT LINE? IS DIRECTLY AS THEIR MASSES AND INVERSELY AS THE SPACE BETWEEN 
NEXT LINE? THEM MEASURED FROM CENTRE TO CENTRE, THE QUANTITY GF THIS SPACE 
NEXT LINE? BEING THENCE MULTIPLIED BY ITSELF. I CALL THIS ATTRACTION THE 
NEAT LINE? LAW OF GRAVITATION ¢THE THEORY OF RELATIVITY: HAVING A BETTER 
NEXT LINE? SGUND, IS TOG CBSCURED. 

NEXT LINE? BUT I HASTEN TO OTHER THINGS. 

NEXT LINE? 

NEXT LINE? IZZY MEWTCON 

NEXT LINE? 

NEXT LINE? wwe enn nnn nnn nn nn nnn nn nn nn ne oo nn en nn nn ne eee 
NEXT LINE? END 


READY 


The file DIARY now contains the strings input above. More than 
two but less than three full blocks are used in this file at this 
point. The second execution of the above program adds information 
to the existing file, beginning at the next empty block (in this 
case, block #4). 
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RUNNH 


NEXT LINE? JULY 6 1686 
NEXT LINE? DEAR DIARY, 
NEXT LINE? THE CYNAMICS GF FALLING APPLES IS HAZARDOUS WORK. HENCE- 


NEXT LINE? FORTH I SHALL CONCENTRATE ON INVENTIONS. I FLAN TO INVENT 
NEXT LINE? DIFFERENTIAL CALCULUS BEFORE SUFFER. 

NEXT LINE? SQ LONG FOR NON, DEAR CIARY. 

NEXT LINE? 

NEXT LINE? 122 MEWTON 
NEXT LINE? END 


READY 


The following program is run to print the contents of the file 
DIARY, from the beginning of the file to the last entry. 


14008 REM THIS PROGRAM READS THE FILE "OIARY. " 
1616 OPEN "DIARY" AS FILE 4% 

1626 ON ERROR GOTO 1666 

1636 INPUT LINE #44, MM 

1646 PRINT M$; 

1658 GOTO 1626 

16968 CLOSE 4% 

1878 END 
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RUNNH 
JULY FS. Léh6 

DEAR DIARY, 

EARLIER TOCAY, WHILST REPOSING “NEATH YE CLGE APPLE TREE, 
T WITNESSED A COMMONFLACE BUT PAINFUL EVENT WHICH METHINKS MAY 
FROVE OF PUBLICK INTEREST. TO WIT: A RIPE AND GOoOr-SIZEL 
RPPLE LOOSENED ITSELF FROM THE TREE AND FELL EARTHWARD. 
STRIKING THIS HUMBLE NARRATOR UPON THE HEAD AND CAUSING HIM TO 
BE DAZED CONSICDERAELY. 

FS A RESULT, METHINES THERE IS AN ATTRACTION BETWEEN BODIES 
I HERE USE THE WORD ATTRACTION IN GENERAL FOR ANY ENDEAVOR 
WHATEVER. MAGE BY BORTES TO APPROACH TO EACH OTHER. WHETHER THAT 
ENDEAVOR ARISE FROM THE ACTION OF THE BODIES THEMSELYES, AS 
TENDING TO EACH OTHER CR AGITATING EACH OTHER EY SPIRITS 
FMITTED; OF WHETHER IT ARISED FROM THE ACTION OF THE ETHER OF OF 
THE AIR. GF OF ANY MEDIUM WHATEVER, WHETHER CORFOREAL OF 
INCORPOREAL, IN ANY MANNER IMPELLING BOGIES PLACED THEREIN 
TOWARDS EACH OTHER. FURTHER, THIS ATTRACTION SETWEEN PARTICLES 
IS DIRECTLY AS THEIR MASSES AND INVERSELY AS THE SPACE BETWEEN 
THEM MEASURED FROM CENTRE TO CENTRE, THE G@UANTITY CF THIS SPACE 
BEING THENCE MULTIPLIED BY ITSELF. I CALL THIS ATTRACTION THE 
LAW OF GRAVITATION ¢THE THEORY OF RELATIVITY, HAVING A BETTER 
SOUND, IS TOO GBSCURE?. 

BUT I HASTEN TO OTHER THINGS. 


Tez NEWTON 


JULY 6, L686 
DEAR GIARY, 
THE DYNAMICS OF FALLING APPLES 15 HAZARDOUS WORK. HENCE- 
FORTH I SHALL CONCENTRATE ON INVENTICNS. I FLAN TO INVENT 
GIFFERENTIAL CALCULUS BEFORE SUPPER 
SO LONG FOR NOW, DEAR CIARY 


T22Y NEWTON 
READY 
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CHAPTER 11 


VIRTUAL DATA STORAGE 


and update records on a disk file in a random (non-sequential) manner. 
Other applications may require more core memory for data storage than 
is economically feasible. BASIC-PLUS fills both these requirements 
with a simple random-access file system called virtual core. 


The BASIC-PLUS virtual core system provides a mechanism for the 
programmer to specify that a particular data matrix is not to be 
stored in the computer core memory, but within the RSTS-11 disk file 
system instead. Data stored in disk files external to the user pro- 
gram remain, even after the user leaves his terminal, and can be 
retrieved by name at a later session. Items within the file are indi- 
vidually addressable, as are items within core matrices. In fact, 
it is the similar way in which data are treated in both core and 
random-access files which leads to the name virtual core. 


With the virtual array facility, BASIC-PLUS programs can operate 
on data structures that are too large to be accommodated in core at 
one time. The disk file system is used for storage of data arrays, 
and only portions of these files are maintained in core at any given 


time. 


With virtual data storage, the user can reference any element of 
one or more matrices within the file, no matter where in the file that 
element resides. This random access of data allows the user non- 
sequential referencing of the data for use in any BASIC statement. 

The virtual core matrices are read into memory automatically by the 
system. 


The order in which array elements are referenced can have a 


significant effect on the program execution time. This section also 
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describes the algorithms used in the virtual array processor, in 
order that users concerned with efficiency can optimize their use 
of this facility. 


Each disk file appears to the user program as a contiguous 
sequence of 256-word records. Any position in a file can be specified 
internally with a two-component address; the first part being the 
relative record within the file, and the second being the position of 
the item within the block. One of the functions of the virtual array 
processor is to transform, or map, each virtual array reference into 


its corresponding file address. 


Virtual arrays are stored as unformatted binary data. This 
means that no I/O conversions (internal form-to-ASCII) need to be 
performed in storing or retrieving elements in virtual storage. Thus, 
there is no loss of precision in these arrays, and no time wasted 


performing conversions. 
11.1 VIRTUAL CORE DIM STATEMENT 

In order for a matrix of data to exist in virtual core, it must 
be declared in a special form of the DIM statement. This special 


DIM statement is as follows: 


Line number DIM# < integer constant >,<list> 


where the tnteger constant is between 1 and 12 and corresponds to the 
internal file designator on which the program has opened a disk file. 
The variable Zist appears as it would in a DIM statement for a core- 
resident matrix. Thus, a 18% by 188 matrix could be defined as: 


1@ DIM #12e%. Acie, 168% 


Floating-point constants, integer constants and strings can be stored 
in virtual core matrices. More than one matrix can be specified in 


one virtual core field. For example: 


25 DIM #14, ACLORe?. BRC Sees. CHCSABas 
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allocates space for 199% floating-point numbers, 299M integer numbers 
and 2598 character strings (16 characters long). However, if a virtual 
array is defined in this fashion, future references should always 


dimension the arrays to the same size. 


11.2 VIRTUAL CORE STRING STORAGE 


One of the few differences in data handling between core and disk 
matrices occurs in the storage of strings within string matrices in 


wan rae + co he aamese a ee ee me eee 
ual core. Strings in the computer memory 


are of variable length 
from @ characters to any arbitrary length. Strings in virtual core 
matrices are of fixed length from @ characters to a specified maximum 
length (all elements of a single string array have the same maximum 
length). This fixed length can be defined by the program and varies 
from 2 characters to 512 characters. The system forces the maximum 


length to be a power of 2; that is, one of the following lengths: 


2, 4, 8, 16, 32, 64, 128, 256, 512 


Each element in the virtual core string need not use the maximum 
length available, even though space is reserved for each element to 
be the maximum size. If the user indicates other than one of the 


values above, he receives the next higher size. Thus: 


48 DIM #10, N¥C185 


nn 


i} 
v7 


is equivalent to: 


JQ DIM #48. Heei1G> = 128 


If no length is specified, a default length of 16 characters is 
assumed. The maximum length of virtual core strings is specified 


as an expression in the DIM statement, using the form: 


line number DIM #<integer constant>,<string (dimenston(s))>=<integer constant> 


For example: 


15 DIM #48. ASC 1@Gs=2ee. Bet ieea4e. CHCL ED 
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where: 


AS consists of 181 strings of 32 characters each, maximum; 
BS consists of 181 strings of 4 characters each, maximum; 


c$ consists of 191 strings of 16 characters each, maximum. 


If a length attribute is given in a DIM statement for an in-core 
string matrix, it is ignored, since core storage is allocated dyna- 
mically to hold a string of any length. 


11.3 OPENING AND CLOSING A VIRTUAL CORE FILE 


In order for the user to reference his virtual core file, he must 
first associate a disk file (by name) with an internal channel desig- 
nator from 1 to 12 (which is then used in the virtual DIM declaration). 
This is done with an OPEN, OPEN FOR INPUT, or OPEN FOR OUTPUT state- 


ment: 


line number OPEN <string> POR peas ] AS FILE <expresston> 
FOR OUTPUT P 


where the string is the name of a disk file and the expression speci- 
fies an internal file designator (this is the same format described 
in Section 9.2); thus: 


“5 GPEN “ACCT“ AS FILE 44 


associates the file named ACCT with internal channel 1. If ACCT 
already exists, then the existing file is used. If there is no file 
named ACCT, one would be created. If the user wishes to destroy an 
old file named ACCT and create a new file of the same name, he can 
use the statement: 


%5 OPEN "ACCT" FOR GUTFUT AS FILE Ls 
which causes the file to be deleted if it already exists and a new file 


created (in which case the file is deleted if not used). If the user 
wants to be alerted that the file ACCT is not present, he could write: 


25 OPEN "ACCT" FOR INPUT AS FILE Le 
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which would cause an error message to be printed if ACCT is not 


found. 
NOTE 


Virtual core arrays do not permit internal 
buffers larger than 512 characters; therefore, 
the RECORDSIZE option is not used when open- 
ing a virtual core array file. 


11.3.1 Pre-Extending a Virtual Array 


Since the system overhead for extending a file by a single data 
element and by many elements is nearly the same, it is much more 
efficient to immediately extend a newly created file to its final 
length than to extend it many times in increments of a single data 
element. Whenever the final size of a file is known, the file should 
be extended to its full size in a single operation. 


For example: 


1@6 OPEN “DATA" FOR QUTFPLIT AS FILE 46 
2G8 DIM #41. ACLeaaEs 
268 AclGeeo> = & 


This extends the virtual core array A to its final length. Virtual 
core arrays, however, are not initially zeroed by the system. In the 
example given above, A(@) through A(9999) contain indeterminate values. 
Unless the user is careful these values could cause a program failure. 
The user is advised to first zero the virtual core array. This could 
be done as follows: 


280 MAT A = SER CAbeaeS 


which both zeros and extends the file to its maximum size. However, 
this uses the more time consuming method of extending the file. A 


more optimal approach would be: 


S68 ACLBaGGe =o: MAT A = ZERC Lene 
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which immediately extends the file to its maximum and then zeros it 


sequentially. These techniques have frequent practical application. 


11.3.2 Closing a Virtual Core File 


The CLOSE statement must be used to terminate I/O between the 
BASIC program and the virtual array. Once a virtual array has been 
closed, it can be reopened for reading or writing on any internal 
file designator. 


All virtual arrays must be closed before the end of program 
execution. The CLOSE statement causes the output of the last data 
element to a virtual core file. Execution of a CHAIN statement 
automatically closes any open arrays, but does not cause the output 
of the last data elements to the array. The format of the CLOSE 
statement is as follows. 


line number CLOSE <expression> [,<expresstion>...] 


The expression indicated has the same value as the expression in the 
OPEN statement and indicates the internal channel number of the array 
to close. Any number of arrays can be closed with a single CLOSE 
statement; it more than one array is to be closed, the expressions 
are separated by commas. The CLOSE statement writes the current 
contents of the I/O buffer to a virtual core file before closing it 
and frees core storage space for the program to open other arrays or 
files (a maximum of 12 depending upon available space). For example: 


E 2,4 
E 16 


Line 255 above closes the virtual arrays opened on internal I/0 
channels 2 and 4. Line 345 closes the array open on internal I/O 
channel 10. 


11.4 VIRTUAL CORE PROGRAMMING CONVENTION 


Recoverable errors occur when using virtual core if the user 
program does any of the following: 
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1s Reference a virtual core array without first opening 
the file. 


2. Reference a non-disk file (for example, DECtape or the 
line printer) as a virtual core array. 


3 Exceed virtual core, that is, define a matrix that is 
bigger than the amount of available disk storage on the 
system. 


It is important to remember that a virtual core file must be closed 
before stopping the program (like any other file). 


11.4.1 Array Storage 


Any data element in a virtual array is completely contained within 
a Single segment (256 words) of disk storage. This restriction has no 
effect on integers and floating-point items, where the size of data 
items is fixed (l-word integer, 2- or 4-word floating point numbers), 
but does limit the maximum length of a virtual string to 512 characters 
(512 bytes). The number of data elements stored in each disk segment 
is a function of the size of each element. For virtual strings, the 
number of elements is also related to the maximum string length speci- 
fied in the DIM# statement. The size of a virtual string is defaulted 
to 16 characters, and can be specified as: 2, 4, 8, 16, 32, 64, 128, 
256, or 512. Table 11-1 indicates the number of array elements stored 
in each segment of a virtual file. 


Table 1li-1 
Virtual Array Storage Capabilities 


Number of Elements 
Data Type per Segment 


Integer (%) 
2-Word Floating Point 
4-Word Floating Point 
String (S$) 


(where the maximum length =N) 
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Strings in virtual storage occupy pre-allocated space in the 
virtual file, and thus differ from strings in core storage, where 
space is allocated dynamically. A disk segment containing virtual 
strings can be considered to be a succession of fields, each of the 
maximum string length. When a virtual string is assigned a new 
value, it is stored left-justified in the appropriate field. If the 
new string value is shorter than the maximum length, the remainder 
of the field is filled with zeros. When the string is retrieved, its 
length is computed as the maximum string length minus the number of 
zero-~filled bytes. 


11.4.2 Translation of Array Subscripts into File Addresses 


In order to translate an array subscript into a file address, 
RSTS-11 computes (a) the relative distance from the specified item 
to the first item in the array, and then adds (b) the relative dis- 
tance from the first element of the array to the first item in the 
file. The first quantity (a) is computed from the array subscript 
and the number of elements per block, as shown in Table 11-1. The 
second number (b) is a constant for each array in a file, and is 


computed from the parameters specified in the DIM# statement. 


Since the DIM# statement contains the only information used to 
define the structure of a file, it is possible for the user to specify 
differently accessing arrangements for the same file in one or more 
programs. For example, the user can reference the same data as 
either a series of 32-byte strings (A2$) or l6-byte strings (Al1$), 
with the following statements: 


18 DIM #1,A1$ (189%) = 16 !16 CHARACTER STRINGS. 
28 DIM #1,A2$(588) = 32 132 CHARACTER STRINGS. 
38 OPEN 'FIL1' AS FILE 1 !IVIRTUAL ARRAY FILE. 


The user should keep in mind that in BASIC-PLUS, as in most 
BASICs, array subscripts begin with @, not 1. An array with dimension 


n, or (n,m) actually contains n+l, or [(n+1)*(m+1)] elements. 
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User programs may define two-dimensional virtual arrays as well 
as singly dimensioned ones. Two-dimensional arrays are stored on 
disk (and in core) linearly, row-by-row. Thus, in the case of an 


array (X1,2), the array appears logically as: 


x(0.8) 


while physically it is stored as: 


lowest address 


highest address 


If a virtual array is to be referenced sequentially, it is 
usually preferable to reference the rows, rather than the columns, 
in sequence. Consider the case in which it is necessary to compute 
the sum of each row and column in a two dimensional array. Program 


ONE does this far more efficiently than program TWO (see next page.) 
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J 


REM FROGRAM “ONE” TO COMPUTE SUMS EFFICIENTLY 
REM "ARRAY" CONTAINS VIRTUAL ARRAY 
REM Rel> IS SUM OF ROW I 
REM Cody IS SUM OF COLUMN J 
CIM #1. AcC1G, Se> '48 ROWS. 3a COLUMNS 
DIM Rela@s, Ccaes 
QPEN "ARRAY" AS FILE 1 ‘OPEN VIETUAL FILE 
HAT BR = 2ER TINITIALIZE SUM 
WAT C = GER 
FOR I = 1 TO 16 TORERATE ROW BY ROW 
For J = 1 TO S@ 'OO EACH COLUMN IN ROM 
Belo = ROIs + ACI, 73 ‘TOTAL ACROSS ROW 
Cody = Cede + ACI, TS 'TOTRL DOWN COLUMN 
NEAT J ‘NEST COLUMN IN ROW 
NEAT I INEST FO 
MAT PRINT BR: 'PRINT ROW TOTALS 
HAT PRINT ¢; 'PRINT COLUMN TOTALS 
CLOSE 1 
END: 
REM PROGRAM “THO° HAS INEFFICIENT USE OF ¥YIRTUAL CORE 
REM "ARRAY" CONTAINS VIETUAL ARRAY 
REM Fels CONTAINS SUM OF ROW I 
REM Ceds CONTAINS SUM OF COLUMN 
DIM #1. Ac1e, 56> '46@ ROWS, Fe COLUMNS 
OIM Rete, Cosas 
OPEW “HRRAY" AS FILE 2 
WAT FR = ZER 
MAT C = ZER 


REM - REFERENCING ARRAY ELEMENTS GOWN THE 
REM - COLUMNS CAUSES EXTRA DISK REFERENCES 
TORPERATE ONE COLUMN AT 


FOR J = 1 TO Sé@ 

FOR I = 4 TO 16 

Belo = Bets + ACI, T3 
Céds = Cida + ACL, go 
NEAT I 

NEAT J 


MAT PRINT FR; 
MAT PRINT Ci 


CLO 
END 


SE 4 


‘ANG EACH ROW IN COLUMN 


‘TOTAL ACROSS ROW 
'TOTAL DOWN COLUMN 
PNEST ROW IN COLUMN 
‘NEAT COLUMN 
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H 


TIME 


In virtual core arrays it is permissible to have two (or more) 
arrays sharing the same file. That is, the following DIM# statement 
is perfectly legal. 


198 DIM#1,A(19G9) ,B% (999) ,C(1P PP) 
The matrix B% begins immediately after the 19#@th element of A 


and the matrix C begins immediately after B%(999). Therefore, the 
disk layout is as shown in Figure 11-1. 


A(B 
A(l 


Figure 11-1 Virtual Array File Layout 


There is, however, an exception to this rule. Elements in string arrays 
are allocated a fixed number of bytes in the disk file. This is either 
2, 4, 8, 16, 32, 64, 128, 256 or 512 bytes of storage. A single string 
element must not cross a disk block boundary (where each disk block 
contains 512 bytes or 256 words). Consider the following case: 


1g DIM A&%(2) ,BS(10PP) =4 
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The first three words of the disk block are allocated to A%. If 
the array BS were to begin immediately after A%, one of the elements 
of B$ would cross a block boundary. Hence, B$ begins at the start of 
the second block in the file rather than immediately after A$. 


The rule can be stated as follows: When more than one array is 
assigned to a single virtual array file, each array begins immediately 
following the last element of the preceding array unless such an 
allocation would cause an element of the array to be split across two 
disk blocks, in which case the array begins at the start of the next 
block of the file, and the remaining words of the current block are 
unused. 


11.4.3 Access to Data in Virtual Arrays 


Only a portion of a virtual array is in core at any given time. 
This data is transferred directly between the disk and an I/O buffer 
in the user core area, created when the OPEN statement is executed. 
This buffer must be 256 words (one segment) long, and may not be 
specified as several segments with the RECORDSIZE option in the OPEN 
statement. For each virtual array file, RSTS-11 notes (1) the seg- 
ment of the file in the buffer, and (2) whether the data in the buffer 


has been modified since it was read into core. 


After RSTS-11 translates a virtual array address into a file 
address, it checks whether the segment containing the referenced item 
is currently in the buffer. If the necessary segment is present the 
reference proceeds; but if not, another portion of the file is read 
into the buffer. If the current data in the buffer has been altered, 
it is necessary to rewrite this dataonthe disk prior to reading new 
data into the buffer. 


The referencing algorithm, which minimizes the number of disk 


memory accesses generated when handling virtual arrays, is flow- 
charted in Figure 11-2. 
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Virtual Arra 
Reference 


Translate Sub- 
script into File 
Address 


Yes 
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Current 
Segment Been 


Altered 
te 


No 


Rewrite Segment 
in File 


Clear 'Modified' 
Indicator 


Read New 
File Segment 


Replac- 
ing Element 


in Buffer 
2 


Set 'Modified" 
Indicator 


Proceed with 
Operation 


Figure 11-2 Virtual Array Accessing Algorithm 
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All references to virtual arrays are ultimately located via file 
addresses relative to the start of the file. No symbolic information 
concerning array names, dimensions, or data types is stored within 
the file. Thus, different programs may use different array names to 
refer to the data contained within a single virtual array file. The 
user must be cautious in such operations, since it is his responsibility 
to ensure that all programs referencing a given set of virtual arrays 
are referencing the same data. Consider the following example: 


Program ONE contains 


16 DIM#41, Kees, Yer 
2@ GFEN "FILE" WS FILE 1 


Program TWO contains 


16 DIM#1, 2¢169, 80189 
26 GFEN "FILE" HS FILE 2 


Whenever program TWO references the array Z, it is using the data 
known to program ONE as array X. Both X and Z are the first arrays in 
their declarations, both contain floating-point data, and both are 

11 elements (X(f@),...,X(18)) long. These two arrays, the, correspond 
in position, type, and dimension. 


References to the array X (in ONE) and to the array X (in TWO) do 
not refer to the same data, even though both are using the same virtual 
file (FILE). The concept of using relative position, rather than 
name, to identify data items is familiar to users of the FORTRAN 
common facility. 


Within a single BASIC-PLUS program it is possible to open a single 
virtual core array file twice on the same channel for the purpose of 
reallocating the data within the file. For example: 


4145 GPEN "GRTA" FoR INPUT AS FILE 1 
156 DIM#t, ASt1ad=4 
155 Dita, BE¢d>=16 


The program now has access to the file DATA through both the array A$ 
and the array B$. Each element of B$ contains four elements of AS 
(B$(%) is equivalent to the elements A$(@) through A$(3), etc.). 
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Note that the two DIM# statements reference that file on a single 
channel number (#1 in this case). 


Note also that the two statements: 


PS DIM#L, Fledes 
SG GlM#L, Beit 


are not equivalent to the statement: 
S@ GIM#L, ACieo, Bee? 


In the first case the arrays A and B are equivalent to each other and 
constitute the first array in the file open on channel 1. In the 
second case the arrays A and B are defined as both existing in the 


file open on channel 1. 
CAUTION 


The user is advised not to open a 
Single file under two different 
channel numbers. For example: 


SS OPEN "SHLUES" AS PIlLe 4 
55 OPEN "VHLUES" AS FILE 2 


LOE DEN#L, eFC Se 
465 DIMN#e, YECees 


causes two buffers to be created for 

the storage of input to/from channel 1 
and to/from channel 2. Data output 

to channel 1 is not available to channel 
2, etc. 


11.4.4 Allocating Disk Storage to Virtual Files 


The dimensions indicated in a DIM# statement set maximum allow- 
able values for subscripts, and are not used to compute the initial 
size of the virtual file to be allocated on disk. Instead, the file 
is created with an initial length of @ segments, and segments are 
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appended to the file, to accommodate the highest referenced file 
address in the array. This permits a user to specify array dimensions 
larger than required at the time the program is written; such programs 
may eventually operate on larger arrays without modification, and 
without tying up disk storage unnecessarily. 


Areas of unallocated disk storage are found only at the end of 
a file. 


As segments are appended to a file, their contents are not 
initialized to zero. The data previously recorded in a segment (when 
it was part of another file) is available to the new owner of the 
segment. Users whose files contain confidential information should 
explicitly overwrite all data in such files, prior to file deletion, 
in order to protect data contained therein. 


To override the dynamic virtual array allocation, reference the 
last element in the virtual array file. This causes all segments in 
the file, up to and including the last, to be allocated. As noted 
above, the contents of these segments as appended to the file is un- 
known. Using the MAT ZER command is advisable if the program depends 


on array values being initialized to a known (zero) quantity. 


11.4.5 Simultaneous Access of a Virtual Core Array by Several Programs 


As mentioned in Section 9.2, only the first program to open a 
file (array) is given write privileges. When a second program attempts 
to modify an array which is already open, the appropriate block is read 
from the disk but changed only in the second user's buffer - not on the 
disk. When the second program references this array and attempts to 
read another block from the disk, a PROTECTION VIOLATION error occurs. 
This is because the system attempts to update the disk with the new in- 
formation in the current block before the required block is read into 
core. Since the second program has no write privileges, the disk 
cannot be updated. A CLOSE operation at this point also results in 
a PROTECTION VIOLATION error for the same reason. Once the job re- 
turns to BASIC-PLUS command level and a NEW, OLD or RUN command is 
executed, a CLOSE is performed on all channels. In this case, no 
write is attempted so the CLOSE is successful. 
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The best way to avoid simultaneous write accessing of a virtual 
core array is to determine whether the user program has write priv- 
ileges. Do this with the STATUS variable (see Section 12.3.5) as 


shown below. 


1@ OPEN "ARRAY" aS FILE tk 
@e6 IF «StHTUS AND deedes THEN CWRITE Locke b> 
ELSE ¢HRITE OKAY? 


MODE 1% should not be used for updating an array by several pro- 
grams simultaneously. This is because a user's buffer is modified 
when an array is open with the MODE 1% option -- the disk is not 
updated at this time. (Even when the first program unlocks the file, 
allowing other programs to access the array, the first program's 
modifications exist only in the first user's buffer.) The array is 
updated only when the first user accesses data from another block, 
as explained above. 


11.5 PROGRAMMING EXAMPLE 


As an example of virtual core usage, consider the problem of 
generating a large array of random numbers. Since a physical disk 
block is 256 words, the most efficient array would contain a multiple 
of 256 elements. The virtual core file, ARRAY1.DAT, in this example, 
contains 5128 data elements in a 2 x 2560 array. The zero row and 
zero column are used, so this array is dimensioned V%(1%,2559%). 
Twenty physical blocks are used to store this array. The program 
shown below creates the virtual array V% by assigning a random value 
between @ and 186% to each element in the array. 


1466 OPEN "ARRAYS. GAT" AS FILE 3x 

1014 GIN #3h, VYECLE, 2559K3 

i226 FOR Ik = @i Ta 1k 

1QS@ VACTA, Jeo = RADCLD * 1660 FOR JE = ak To 2559" 
1646 NEXT Is 

1656 CLOSE Ee 

1066 ENG 
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Now that the file ARRAY1.DAT has been created, 


the virtual array 


can be accessed simply by specifying the elements by their subscripts. 


The program shown below prints every 256th value. 


Notice that the 


format of the array in the DIM statement, below, must be identical to 


the original format for predictable results. 


The file's internal 


channel number and the array's name can change, but the array must be 


formatted the same way every time it is accessed. 


1006 OFEN “ARRAY1. DAT" AS FILE 32 

1016 DIM #34, V“C14, 2559%3 

1626 FOR Ix = 6% TO 14% 

1636 PRINT VACIZ, d49; FOR Ja=@2 TO 25594 STEP 256% 
1040 NEXT Ie 

1056 PRINT 

1866 CLOSE 3% 

1676 END 

READY 

RUNNH 

204 969 954 839 65 4314 S37 764 E71 798 S65 173 tee 


468 956 289 


READY 


316 


Values of array elements can be changed simply by redefining 


them in assignment statements (e.g., LET, INPUT, READ) . 


For example, 


the program below changes the value of specified data elements, once 


they are defined by subscripts. 


GQFEN "ARRAYS. GAT" AS 
DIM #34, VECLa, 2555e2 
4026 ON ERROR GOTO i8&a@ 
1620 INPUT "ENTER THE I AND J LOCATION OF THE ELEMENT"; 
1644 Ne = Wacla, Jeo 

41656 INFUT “ENTER THE NEW YALUE"S 
106@ FRINT “OLO VALUE WAS: " Ne ". 
1676 GOTO 1836 

1686 CLOSE 3a 

1696 END 


1666 FILE 32 


1616 


YVetle. Jeo 


NEW VALUE 15: " 


REALS 
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le, Js 


Yatla, Jas 


RLIMAH 

ENTER THE IT ANG J LOCATION GF THE ELEMENT? @.4@ 
ENTER THE NEW VALUE? 3233 

OLD VALUE WAS: 264 . NEW VALUE I5: 335 

ENTER THE I ANG J LOCATION OF THE ELEMENT? &. 255 
ENTER THE NEW VALUE? 99% 

OLO YALUE WAS: Fe. NEW VALUE 15: 359 

ENTER THE IT ANG J LOCATION OF THE ELEMENT? 1. 568 
ENTER THE NEM VALUE? 42 

OLD VALUE WAS: 263 . NEW VALUE IS: 4 

ENTER THE IT AND J LOCATION OF THE ELEMENT? “2 


READY 


Some thought should be given to access methods of virtual arrays. 
In the above examples, ARRAY1.DAT was allocated in the following 


manner: 
Block 1 V(g,8) - V(B,255) 
Block 2 V(@,256) -V(@,511) 
Block 3 V(6,512) - V(S,767) 
Block 1% V(S,2384) - V(g,2559) 
Block 11 V(1,f) - V(1,255) 
Block 2g V(1,2384) - V(1,2559) 


Notice that the second subscript varies from § to 2559 for each 
of the two values (@ and 1) of the first subscript. Since the system 
transfers an entire physical record from the disk to core at one time, 
only one disk access is performed for each 256 consecutive data 
elements (e.g., V(#,256) - V(@,511)). It is therefore much more 
efficient to access data elements within a given block than to access 


data elements in different records. 


The two programs shown below access, but do not print, each 
element in the virtual array. The first access method transfers a new 
block to core for each data element accessed, resulting in 5,120 disk 
accesses. The second method, however, transfers a new block to core 
only once per 256 data elements, resulting in only 20 disk accesses. 
The difference in execution time between both methods is very signi- 


ficant, as shown below. 
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Program #1 
(Inefficient) 


1606 OFEN "ARRAYL. CAT" AS FILE 3h 

1616 DIM #38, VYeCLA, 2559n3 

1626 T = TIME<a@> 

1636 FOR Je = Gk TO 2@559% 

1640 De = WACTA. Jao FOR In = 62 TO ik 

1656 NEXT Je 

1066 FRINT "THE FIRST ACCESS TOOK" TIME¢@3-T " SECONDS. * 
1676 CLOSE 3h 

166@ END 


READY 


RUNNH 
THE FIRST ACCESS TOOK 148 SECONDS 


READY 


Program #2 
(Efficient) 


1606 OPEN "ARRAY. GAT" AS FILE 38 

1446 DIM #3n, Vacta, e559n> 

1626 T = TIME¢@> 

1636 FOR Ie = 6% TO 4s 

1646 De = YeCIa, Jeo FOR Je = @e To 25568 

165@ NEXT Ia 

1666 FRINT "THE SECOND ACCESS TOOK" TIME*@>-T " SECONDS. " 
1676 CLOSE 3x 

1986 END 


REAGY 


RUNNH 
THE SECOND ACCESS TOOK & SECONDS 


READY 
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CHAPTER 12 


RECORD I/O 


There are three methods of performing I/O in BASIC/PLUS. For- 
matted ASCII I/O is simple and flexible, but requires conversion of 
numbers by the system from an internal form to an externally usable 
ASCII representation and does not permit random access to files. I/0 
to virtual core arrays permits high-speed random access to files but can 
be used only on disk files and does not allow true intermixing of 
string and numeric elements or use of the RECORDSIZE specification. 


The third type of I/0, Record I/O, permits the user program to 
have complete control of I/O operations. Properly used, Record I/O 
is the most flexible and efficient technique of data transfer avail- 
able under BASIC-PLUS. These advantages are obtained at the cost of 
the simplicity of the formatted ASCII and virtual array I/O. Less 
experienced users should first experiment with the simpler I/O tech- 
niques before attempting Record I/O. 


12.1 OPENING A RECORD I/O FILE 

To open a file for Record I/O requires an OPEN statement, des- 
cribed in Section 9.2. An additional field has been added to the OPEN 
statement: the MODE field. The format of the OPEN statement, in- 


cluding the MODE field, is as follows: 


FOR INPUT 


[Line number] OPEN<string> [op ouTPuT! 


AS FILE <expr> 
[, RECORDSIZE < expr>] [, CLUSTERSIZE <expr>] [MODE <expr>] 


[,FILESIZE <expr>] 
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The MODE option is used to establish device-dependent properties of the 
file. For disk files MODE indicates that the file is to be opened to 
update data (see Section 12.4.5). For non-file structured magtape 
operations, MODE establishes the density and parity settings for the 
magtape. For line printer operation, MODE is used in conjunction with 
the optional forms control to establish the current form length. For 
card reader operation, MODE sets a read mode to correspond to specific 
data card formats!. 


The RECORDSIZE and CLUSTERSIZE options can be specified for Record 
I/O files as described in Sections 9.2.1 and 9.2.2. 


12.2 CLOSING A RECORD I/O FILE 


Each Record I/O file must be closed once I/O operations on that 
file are completed. Files are closed with the CLOSE statement, as 
described in Section 9.3. The CLOSE statement is of the form: 


line number CLOSE <expr>[,<expr>] 


where the value of the expression(s) specifies one of the twelve I/O 
channels. 


Remember, the CLOSE statement for formatted ASCII and virtual 
array files causes the the final record of the file to be written 
before closing the file. However, all I/O to Record I/O files is 
explicitly performed (with GET and PUT statements). For this reason, 
be sure the user program explicitly writes the last record onto a 
Record I/O file before executing a CLOSE. 


12.3 THE GET AND PUT STATEMENTS 


Input and output to Record I/O files is performed directly 
between the device channel and the I/O buffer created by the OPEN 
statement. All I/O is specified in terms of single records, using 
the GET and PUT statements. GET and PUT are of the form: 


line number GET# <expri1> [,RECORD <expr2>] 
line number PUT# <expr1> [,RECORD <expr2>] [,COUNT <expr3>] 


1 


See the RSTS/E Programming Manual for details. 
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If the RECORD option (see Section 12.3.3) is not used, the GET 
Statement reads the next sequential record from the file open on the 
channel designated by <exzprl>. The record is placed in the I/O buffer 
which was associated with the channel by the OPEN statement. The 
size of the record depends upon the characteristics of the device on 
which the file resides, as described in Table 12-1. In Record I/o, 
the RECORD option refers to a 512-byte sector, not to a logical data 
record. 


When the RECORD option is used in a GET or PUT statement, a 
specific record, or sector, is accessed. For example, 


198 GET #4%, RECORD 8% 


reads the eighth sector of the file opened on channel 4 into the user 
I/O buffer. Notice that the preceding 7 sectors of the file need not 
be read. This feature, not available in formatted ASCII files, is 
called random access. 


Table 12-1 
Device Record Characteristics 


Input Record Characteristics 


Records (sometimes called blocks or segments) 
are always 512 characters long. When the 
RECORDSIZE option is specified in the OPEN 
statement, and a buffer longer than 512 
characters is created, the system reads as 
many full records as possible. If several 
disk records are read with a single GET state- 
ment, the next sequential record is that record 
immediately following the last record read. 
In non-file structured operation, the minimum 
record size is dependent on the device cluster- 
size. 


DECtape For file structured DECtape, records are always 
510 characters long. For non-file structured 


DECtape, records are always 512 characters. 


magtape When performing file-structured I/0, magtape 
records are always 512 characters. With non- 
file structured I/0, magtape records can be 

of any length; only one record can be read 

per GET statement; and the record length can 
not exceed the buffer size as determined by the 
RECORDSIZE option. 
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Table 12-1 (Cont.) 
Device Record Characteristics 


Input Record Characteristics 


keyboard The GET statement obtains one line from the 
keyboard, up to the first line delimiter 
(CTRL/Z, RETURN, LINE FEED, ESCAPE or 
FORM FEED). 


card reader A record consists of a single card. The 
RECORDSIZE option has no effect on card 
reader input. 


paper tape RSTS-11 reads afull buffer of input from the 
paper tape reader unless an end-of-tape is 
detected. 


Similarly, if the COUNT and RECORD (see Sections 12.3.2 and 
12.3.3) options are not used, the PUT statement writes the contents 
of the 1/0 buffer for the specified I/O channel onto the next 
sequential record of the file. The expression < exprl> specifies the 
internal channel number on which the file was opened. PUT writes 
a single record on the device, with the exception of disk files which 
permit several records to be written with one PUT statement (when 
the RECORDSIZE option in the OPEN statement is used to increase I/O 
buffer size). 


12.3.1 The RECOUNT Variable 


Non-file structured devices, as can be seen in the description 
of the GET statement, can read less than a full buffer of data. To 
permit the program to determine how much data was actually read, a 
system variable, RECOUNT, contains the number of characters read 
following every input operation. 


RECOUNT is used primarily for non-file structured input; however, 
it may also be used with file structured devices. On file structured 
DECtape and magtape input, RECOUNT is set to the standard record 
length (518 characters for DECtape and 512 characters for magtape) . 
On disk file input, RECOUNT is set to the RECORDSIZE. If the 
RECORDSIZE is not an integral multiple of 512, an error message is 
printed. 
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RECOUNT is set by every input operation on any channel (including 
channel 9). It is, therefore, essential that the RECOUNT value be 
tested immediately following the GET statement. 


12.3.2 The COUNT Option 


The COUNT option used in a PUT statement with a non-file 
structured device specifies the number of characters to write in the 
current record. However, the COUNT expression cannot be greater than 
the size of the I/O buffer. 


For example, where internal channel 1 is opened as magtape 
unit @ (non~file structured magtape), the following statement could 
be used to write an 80-character record: 


iG@ PUT #12. COUNT &@% 


When COUNT is not used, the PUT statement writes an entire buffer, 
regardless of whether the buffer contains data. 


12.3.3 The RECORD Option 


With disk files, the user has the capability of performing 
random access I/O to any record of the file. Records in a disk 
file are always 512 characters long and are logically numbered 
within the file from 1 to n, where n is the size of the file. 


The RECORD expression provides the logical record number of 
the file to GET or PUT. For example, assuming a disk file opened 
on internal channel 1, the following statement writes the contents 
of the I/O buffer associated with channel 1 on records 19 through 99 
of that disk file: 


208 PUT #48, RECORD Ik FOR Te=18e To gan 
More than one physical record or block can be read or written by 
assigning a large I/O buffer to the file with the RECORDSIZE option 


in the OPEN statement. (The size of the buffer does not affect the 
numbering of the records within the file.) 
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If the disk file on channel 1 were opened with a RECORDSIZE of 
1924 characters (which would cause two 512-character records to be 
written with each PUT) the PUT statement would be written as follows: 


26@ PUT #124, RECORD Te FOR Te=1te TO She STEP fe 


After performing a random access GET or PUT on a disk file, the 
next GET or PUT statement on that channel accesses the next sequential 
record if no RECORD number is specified. For example: 


29@ GPEN "“CATA" AS FILE ta. RECORODSITZE olen 
=@@ GET #42, RECORD 99% 
21@ PUT #46 


The PUT statement at line 318 writes record 1§@ of the disk file. 


12.3.4 BUFSIZ Function 


In certain applications, it is important for a program to 
determine the buffer size of an open channel, especially if the 
OPEN statement specifies a logical device name. The user program 


can execute the integer function BUFSIZ to extract this information. 


The BUFSIZ function returns an integer value telling the size 
of the buffer for a specified open channel. For example, 


Y% = BUFSIZ(N) 


The statement returns to Y% the size of the buffer in number of 
bytes for channel N. If the channel is closed, the function returns 
g to Y%. 


12.3.5 STATUS Variable 


The variable STATUS contains information concerning the last 
channel on which a user program executed an OPEN statement. The 
variable is a 16-bit word, each bit of which the user program can test 
to determine status. Table 12-2 shows the information, the tests, 


and the meaning of each bit. 
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13,15 


14 


1Pseudo keyboards always attempt to use handler index 16. 
slot is filled, however, it proceeds to handler index 18. 


(STATUS ANTI 255%) 


(STATUS AND 2564)220% 


(STATUS ANID 512%) 250% 


KSTATUS AND 1024%) 220% 


KSTATUS ANIt 2048%)=0% 


STATUS AND 4096% 


IF STATUS «0% ANID IF 
(STATUS ANI! 81924) «20% 


IF STATUS «0% ANI IF 


(STATUS AND 8192%4)=0% 


IF STATUS +=0% AND IF 
(STATUS AND 8192%) 950% 


IF STATUS ==0% AND IF 
(STATUS AND 8192%)=0% 


IF (STATUS AND 
16384%) «> 0% 


Table 12-2 
RSTS Variable STATUS 


The first 8 bits of the word contain the 
The following values apply 


handler index. 
for various devices. 


Disk 12 Card Reader 
Keyboard 14 Magtape 
4 DECtape 16 PK:device! 
6 Line Printer 18 DX:device! 
8 HS Reader 20 RJ:device? 


10 HS Punch 


The device is open in non-file structured 
mode or is characteristically non-file 
structured. 


The job does not have read access to the 
device. 


The job does not have write access to the 
device. 


The device maintains its own horizontal 
position. Such devices are keyboard and 
line printer type. 


Not used. 

Device is a character device which can be 
controlled by variable RECORD <expr> 
modifiers. Such devices are keyboard, 
line printers, and card readers. 


Device is a random access blocked device 
such as disk and non-file structured DECtape. 


Device is a character device which cannot 
use RECORD modifiers. 


Device is sequential blocked such as 
file structured DECtape and Magtape. 


Device is an interactive type (keyboard). 


If this 
If both 


these slots are filled, it attempts to fill handler index 20. 
Finally, if all three of these slots are filled, the system returns 
an error message. 


The RJ device, if present, always fills handler index 20, but pseudo 
keyboards and all other non-standard devices can fill handler index 
16, 18 and (if RJ is not present) even handler index 20. 
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12.4 WORKING WITH RECORD I/O FILES 


Techniques for opening, closing, reading and writing Record 
I/O files have been described. But these techniques apply only to 
indivisible I/O buffers associated with internal channels; no mention 
has been made of manipulating data within these buffers. Techniques 
for moving data into or out of a buffer are provided by extensions 
to the BASIC language. The FIELD, LSET and RSET statements permit the 
program to access and modify the contents of an I/O buffer, character 
by character. These statements are discussed in the following 
sections. 


12.4.1 Extending Disk Files 


A disk file that is created by an OPEN FOR OUTPUT (or OPEN) 
statement has a length of #. As records are written, the file pro- 
gressively grows in length; this growth is called extending the file. 


A more exact description of file extending is as follows: 


a) Is there room in the last cluster! of the file for the 
new record? 


b) If so, then the file length is increased and previously 
unused space in that cluster is used. 


c) If not, then a new cluster is appended to the file. 
There is then room in the newest last cluster for the 
new record so condition b) applies. 


The amount of space actually allocated by the system to a file 
may be greater than the file length. For example, if the file 
clustersize is 4 and the first 6 records of that file have been 
written, the file is of length 6 but is actually allocated 8 records 
(2 clusters) of space. 


A file is extended by attempting to write beyond the current 
end-of-file. Hence, a program must have write privileges in order 
to be able to extend a file. There is an exception to the rule that 
having write access to a file permits a program to extend the file. 
When a file is opened for update (see Section 12.4.5) several pro- 
grams can have simultaneous write privileges on a single file. 


INote that the file CLUSTERSIZE is the least increment by which a 
disk file can be extended. (See Section 9.9.2.) 
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Nonetheless, if a program opens a file in this special update mode, 
that program may not extend the file. A file can only be extended 
when open in normal (non-update) mode. 


It is possible to extend a file by a number of records at one 
time. For example: 


16@ OPEN "DATA" FOR GUTFUT AS FILE 48 
26@ PUT #4%, RECORD 1868 


creates a file DATA and (when line 200 is executed) extends it im- 
mediately to 10% records. Since the system overhead for extending a 
file by a single record and by many records is nearly the same, it 
is much more efficient to immediately extend a newly created file to 
its final length than to extend it many times in increments of a 
single record. Whenever the final size of a file is known, the file 


should be extended to its full size in a single operation. 
12.4.2 The FIELD Statement 


The FIELD statement is used to dynamically associate string 
names with all or part of an I/O buffer. The FIELD statement has the 
form: 


line number FIELD #<expr>, <expri> AS <stringvari1> 


[,<expr2> AS <stringvar2>...] 


where <expr> is an internal channel number associated with some file 

by an OPEN statement; <expri> is the length, in characters, of the 
associated string variable; and <stringvar1> is a unique string 
variable name. The names are associated from left to right with suc- 
cessive characters in the I/O buffer assigned to the designated internal 


channel number. For example: 


75 FIELO #2h, 162 AS AG. 260 AS BE. EX AD FE 


B$ 


be | 
<—_ 512 -byte buffer 
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As shown in the previous diagram, statement 75 associates three strings, 
A$, B$, and F$ in the I/O buffer, with lengths of 19, 28, and 3 charac- 
ters, respectively. The total number of characters represented in this 
statement is 33. The total number of characters must be less than or 
equal to the actual I/O buffer size (which is dependent on the device 
and the RECORDSIZE option, as described in Section 9.2.1). 


FIELD statements do not move data but rather permit direct access 
to sections of the I/O buffer via string variables. The effect upon 
a string variable is temporary and is nullified by any attempt to 
assign a value to the variable (other than the LSET and RSET, described 
in Section 12.4.3). For example: 


166 OPEN "FILE" AS FILE Ze 
116 FIELD #2h, Se AS AF 
12@ LET Af = "“ABCDE" 


Line 12% causes the string variable AS to be removed from the 1/0 
buffer. The string ABCDE is not stored in the I/O buffer by line 
128. 


A FIELD statement is an executable statement, rather than a 
compiler directive (such as a DIM statement). To illustrate: 
suppose that each record of a disk file contains sixteen 32-character 
sub-records and that each sub-record consists of one 5-character 
field and one 27-character field. In order to extract the eighth 
sub-record from the I/O buffer, the following statement could be 
executed: 


2@@ FIELD #ie. S24e AS OF. Sh OAS BF, Fre AS AF 
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Line 29% causes the string variables BS and A$ to point to the 
desired sub-record. The string DS is created to permit the first 
seven sub-records (7x32=224) to be skipped. An even more general 
statement could be used to obtain any of the sub-records in the I/0 


buffer, as follows: 


196 FOR Te = 2 To 15% 
#06 FIELD #42, CIe-tkoesen AS be, SE AS Bt, SPR AS Ag 
#1G NEXT Is 


f y 


[%=] T%=2 1%=3 I%*4 T%=5 I%=6 I%e7 I%=8 I%=9 


When the statement above is executed, I% should contain the number of 
the sub-record that B$ and A$ are to contain, as an integer from 1 

to 16. When I%=1, for example, the expression (1I%-1%) *32% equals 
zero, so B$ points to the first sub-record in the buffer. When I3=2, 
however, the expression (I%-1%)*32% equals 32, so BS now points to the 
first sub-record beyond the 32nd character of the buffer. Each single 
increment of I% moves B$ 32 characters further into the buffer. 


Subscripted string variables can also be used in FIELD statements. 
For example, the following statements could be used to allocate the 
sub-records, described in the previous example, to two string arrays: 


406 DIM AFC159, Bei 53 

316 FOR Ik = Ge TO 156 

$2@ FIELD #18, Tk#2@h AS OF, Se AS BSC Ind, BFK AS ACTED 
436 NEXT Ih 


B$(3) B$(4) B$(5) BS(6) B$(7) 


Bg(Q) B$(1) 8$(2) 


ee ee ! t 1 ! 1 
aa oa a oa aa ~ + - 


12-11 


With each iteration of the FIELD statement at line 329 the dummy 
string D$ increases by 32 characters, making the displacement from 
the start of the I/O buffer to the string B$(I%) equal to 32 times 
I% characters. Once this loop is executed, the position of each 
string in the arrays A$ and B$ is fixed, A$(#) and B$(#) pointing to 
the first sub-record and A$(15) and B$(15) to the last. 


However, virtual array strings must not be defined as string 
variables in a FIELD statement. When strings are defined as virtual 
arrays they are required to be in a fixed place in both a disk file 
and the I/O buffer for that file. Attempting to specify a virtual 
array string variable in a FIELD statement has no effect on the 
virtual array string. 


12.4.3 LSET and RSET Statements 


Once the strings have been defined as part of the I/O buffer by 
a FIELD statement, values in these strings can be stored without 
moving them from the I/O buffer. The LSET and RSET statements store 
values in a string without redefining the string position. These 
statements are of the form: 


line number LSET <stringvar> [,<stringvar>...] =<string> 


line number RSET <stringvar> [,<stringvar>...] = <string> 
where <stringvar> represents any legal existing string variable name 
(multiple string variable names can be separated by commas) and 
<string> represents any legal string expression. 


LSET and RSET store the value of the string expression into 
the designated string or strings. The string previously stored in 
the variable is overwritten. The length of the string is not changed; 
if the new string is longer than the existing string, the new value 
is truncated. If the new string is shorter than the existing string, 
it is either padded with spaces on the right by LSET or padded with 
spaces on the left with RSET. LSET, then, causes the string to be 
left-justified in the field and RSET causes the string to be right- 
justified. 
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The normal use of LSET and RSET, as described in this section, is 
to store data in strings allocated within an I/O buffer by a FIELD 
Statement. LSET and RSET can be used to assign a value to any string 
variable within a BASIC-PLUS program. 


12.4.4 Differences Between the LET Statement and the LSET/RSET 
Statement 


The LET statement cannot be used to place string values into an 
I/O buffer as it causes the string to be redefined elsewhere. Another 
restriction on LET occurs when that statement is used to equate two 
strings, as follows: 


50 LET A#=BE 


To avoid unnecessary character manipulation, this operation causes 
A$ and B$ to reference the same string. Normally, any operation 
which alters B$ causes that string to be moved, so no conflict 
arises. However, LSET and RSET do not move strings; they alter 
existing strings in a fixed position. 


Therefore, if the value of B$ in line 5f above were altered by 
an LSET or RSET statement, the value of A$ also changes. For 


example: 
4@@ B# = “ABC" 
41@ AF = BF 
42@ LSET Bf = "KYZ" 


Both A$ and B$ contain "XYZ" following the execution of line 429. 


This phenomenon has another ramification; if the string BS in 
this example had been defined by a field statement as being in some 
I/O buffer, the string A$ would also be in the I/O buffer (being 
identical to B$). Executing a GET statement to read another record 
into the I/O buffer would then change the value of AS as well as 
BS. For this reason, LSET and RSET should be used only for Record 
I/O operations; using these statements for other purposes may cause 
illogical results. 


12-13 


When it is not desirable for the strings A$ and BS to be physi- 
cally identical, there is a means of causing the string B$ to be moved 


into the string A$. This operation is performed as follows: 
306 LET Af = BS + "" 


Line number 38@ appends a null string to BS, which has no effect on 
the string A$ but causes the two strings to occupy different storage 
areas. 


12.4.5 Update Option for Disk Files’ 


In the description of disk files up to this point, the concept 
of simultaneous user access to a single file has been largely ignored. 
The system permits several users to read from a single file simul- 
taneously. However, a problem arises if multiple users attempt to 
write onto a single file simultaneously. Two users could conceivably 
try to write the same record of the file, resulting in a loss of data. 
To avoid this conflict, the system permits only one user at a time to 
have write privileges on any given file. Thus, a user may fail to 
obtain write privileges even if the file is not protected against 
writing. If this occurs, the user must close the file and reopen it 
at a later time, after the other user has finished with the file and 
closed it. 


In certain applications (for example, sales order-entry applica- 
tions) it is often normal for multiple users to be updating a single 
master file. In these cases it is not satisfactory to be constantly 
closing and reopening the file to obtain write privileges, as this 
is a time-consuming operation. For this reason a special MODE option 
is available that permits multiple users to have write access to a 
file while guarding against simultaneous writing of a single block. 


To indicate that a file is being opened for update, the MODE 1% 


specification is used when the file is opened. For example: 


100 OPEN "MASTER" AS FILE 1%, MODE 1% 


1Update by MODE 1% is an optional feature of RSTS/E and may not be 
available in all systems. 
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when used with a disk file indicates that the file is opened!. In 
this case the program is granted write privileges unless such access 
is specifically prohibited by the protection code of the file. 


A file cannot be simultaneously open for update by one user 
and open in normal (non-update) mode by another user. Attempting to 
open a file for update if it is already open in normal mode, or 
attempting to open a file in normal mode if it is already open for 
update, results in a PROTECTION VIOLATION (ERR=1f) error. 


Once a file has been opened for update, any read operation of a 
specific physical record puts it in a special locked state. No other 
user is permitted to read or write that physical record until it is 
released (or unlocked) by the program that locked it. Attempting to 
read or write a record that another user has locked results in a 
DISK BLOCK IS INTERLOCKED (ERR=19) error which can be trapped with an 
ON ERROR GOTO statement. There are five ways for a program to un- 
lock the record: 


l. The next write operation on the file unlocks the block. 


2. Executing the UNLOCK statement. This statement has the 
form: 


line number UNLOCK <ezxpr> 


where <expr>is the internal channel number of the file 
that is opened for update. 


33 Any error encountered while accessing the file unlocks 


the block. 

4. Reading another block unlocks the currently locked 
block. Any read operation locks the block just 
retrieved. 

5. Executing a CLOSE statement on the file unlocks the 
block. 


To illustrate MODE 1%, consider a simple inventory application where 
operators on several terminals can access one file to enter a part 
number and order quantities. Assume that the file is sequenced in 
such a fashion that each part number actually corresponds to the 
block number that contains information about the part, and that the 
first four characters of the 512-byte block contain the quantity 


‘The RECORDSIZE option may not be used on files that are opened with 
MODE 18. 
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available as a (2-word) floating-point number. For this example, the 
remaining 5%8 characters are ignored. A program to update the quantity 
available is as follows: 


166 ON ERROR GOTO 1Hee ‘FING OUT ABOUT ERRORS 
2706 OPEN “INVENT. ORY" AS FILE 4. MODE 4 'ORPEN FILE IN UPDATE MODE 
34@@ FIELD #1, 4 AS CF 'c# 15 OTY IN FILE 

406 INPUT “PRET NUMBER’; NG "QUANTITY"; @ 'GET FART # AND GT 

506 GET #4. RECORD N ‘READ APPROPRIATE RECORD 
66@ 8% = CV¥YTS$FcC#o-8 COMPUTE &@TY REMAINING 
766 IF X>=@ THEN &6@ 'TENQUGH GON HANG? 

Pi@ UNLOCK #2 ‘PERMIT OTHER ACCESSES 
Pe@ PRINT "ONLY"; CVTH#P C83; "ITEMS LEFT" !REFORT STOCK LEYEL 

r36 GOTO 466 'REVISE ORDER? 

666 LSET C# = CYTFECR? ‘STORE NEW GTY ON HANG 
656 PUT #4. RECORD N ‘REWRITE INTO FILE 

$66 GOTO 484 'NEST TRANSACTION 

146668 IF ERR <> 19 THEN ON ERROR GOTO &@ 'IGNORE NON-INTERLOCK ERRORS 
116@ FRINT "WAITING" ‘LET HIM ENGH HERE HERE 
1266 SLEEP 5 'HAIT FOR CORRENT ACCESS 
142606 RESUME Sa ‘TREY AGAIN 

1466 ENG 


MODE 5% (MODE 1%+4%) is used to provide an additional protection 
feature. When a file is opened with this special update option, the 
user program can write a block only after it has read it. In other 
words, a PUT operation can be executed only after a GET operation has 
previously input the block into the I/O buffer. Attempting to write 
a block that was not previously read results in a PROTECTION VIOLATION 
error. 


12.5 CVT CONVERSION FUNCTIONS 


The FIELD, LSET, and RSET statements allow a program to store 
or retrieve string data directly from an I/O buffer. To permit 
floating-point and integer values in Record I/O files, four conversion 
functions are provided as described in Table 12-3. A fifth conversion 


function facilitates character string manipulation. 
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Table 12-3 
CVT Conversion Functions 


CVT%S (1%) Maps an integer into a 2-character string. 


CVTS% (AS) maps the first two characters of a string 
into an integer. If the string has fewer 
than two characters, null characters are 
appended as required. 


CVTFS (X) maps a floating-point number into a 4- or 
8-character string (depending upon whether 
the 2-word or 4-word math package, respec- 
tively, is being used on the system). 


CVTSF (AS) maps the first four or eight characters 
(depending upon whether the 2-word or 4- 
word math package, respectively, is being 
used on the system) of a string into a 
floating-point number. If the string has 
fewer than the required number of characters, 
null characters are appended. 


TS = CVTSS (SS,M%) converts the source character string S$ 
to the string referenced by the variable 
TS, The conversion is performed according 
to the decimal value of the integer. 
represented by M% as follows: 


Trim the parity bit. 

Discard all spaces and tabs. 
Discard excess characters: 

CR, LF,FF, ESC, RUBOUT, and NULL. 
Discard leading spaces and tabs. 
Reduce spaces and tabs to one 
space. 

Convert lower case to upper case. 
Convert [ to ( and ] to). 
Discard trailing spaces and tabs. 
Do not alter characters inside 
quotes. 
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Four of the functions do not affect the value of the data, but rather 
its storage format. Each character in a string requires one byte of 
storage (8 bits); hence, characters may assume (decimal) values from 
@ through 255 and no others. A 16-bit quantity can be defined as 
either an integer or a 2-character string; 2-word floating-point num- 


bers can equally be defined as 4-character strings. 


The CVT functions which change storage format perform two impor- 
tant functions: first, they permit dense packing of data in records. 
For example, any integer value between -32768 and 32767 can be packed 
in a record in two characters using CVT%$; this would only be true 
for integers between -9 and 99 if the data were stored as ASCII 
characters. Second, converting the internal numeric representation 
to an ASCII string (as with the NUMS$ function) is a more time- 
consuming process than that performed by the CVT functions. Thus, the 
CVT functions provide the means to speed the processing of a large 
amount of data within a file. 


The CVTS$ function manipulates a character string and generates 
a new character string. This action is unlike other CVT functions 
because it does not change the internal format of the data, but 
rather alters the contents of the string. The output string is con- 
verted according to an integer value given by the user program and 
can be any value or sum of any values listed in Table 11-2. 


The value 1% in the CVT$$ function removes the parity bit (most 
significant bit) from each character in the string. Under RSTS-11, 
characters are usually represented with no parity. All comparison 
of characters assume no parity. The value 2% removes all space 
characters (CHR$(32)) and horizontal tab characters (CHRS$(9)) from 
the string while values 8%, 16%, and 128% remove only selective 
occurrences of space and horizontal tab characters. The terminating 
and excess characters removed by the value 4% in the CVTSS function 


usually have no informational value in a string. 


The value 32% converts all lower case characters in a string to 
upper case. This feature is valuable since some terminals transmit 
both forms of alphabetic characters. The lower case characters are 
between CHR$(97) and CHR$(122) and upper case characters are between 
CHRS$ (65) and CHR$ (90). 
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The value 64% in the CVT$$ function enables BASIC-PLUS programs 
to accept the parenthesis and square bracket characters as delimiters 
of a project-programmer number. This action is desirable when handling 
account numbers from terminals not having the square bracket charac- 


ters since most terminal devices have the parenthesis characters. 


The value 256% in the CVTS$ function forbids any alteration of 
characters inside quotes, except parity bit trimming - set by M%=1%. 
Regardless of other values in the parameter M%, when 256% is included 
no operations are performed in the source string on characters within 


quotes. 


Generally, the precedence of operations performed on the string is 
in increasing order of the individual values in the parameter M%. 
(The 256% value, however, is the exception; its precedence ranks 
between 1% and 2%.) This order implicitly determines which sub- 
sequent operations are performed on the string. For example, if the 
characters in the source string have their parity bit set and the 
parity trimming option is not selected, subsequent comparisons 
required by other options are possibly not successful because com- 
parisons are made against ASCII characters with no parity. For 
example, a space (SP) character, which is CHRS$(32) (octal 40) in no 
parity or odd parity form, does not compare with a space (SP) charac- 
ter which is CHR$ (160) (octal 240), its even parity form. 


Keeping the parity bit in the input character of the string is 
important in text processing applications where the parity bit of 
each character is possibly a flag rather than a parity bit. Asa 
result, such flagged characters are not changed or discarded if the 
parity trimming option is not selected. 


The precedence of operations affects the result of values given 
in the CVTSS function. If the values 2%, 8%, 16%, and 128% (154% 
or greater) are given in the CVTS$ function, the values 8%, 16%, 
and 128% have no effect on the output string since the first option 
performed (2%) removes all space and tab characters from the string 
and the remaining values dealing with space and tab characters have 
no effect. In like manner, the value 16% applies to all space and 
tab characters not discarded by the 2% and 8% options. Accordingly, 
to maintain at least a single space interval in a string, the user 
program must give the 16% value and omit the 2% and 8% values. 
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The use of the CvTS$ function in general eliminates the need for 
special code in BASIC-PLUS programs handling string input. For 
example, the following code at lines numbered 110 through 114 mani- 
pulates an input string. 


95 DIM Réecie8es 

$6 N1n = Le 

1466 PRINT "TYPE THE INFUT STRING"; : INPUT LINE AGF 

185 T# = FNCESc AEs) 

410 DEF FROEFCAGES 

414 CHANGE AG TO Ree: Jék = Ba: FOR kéex = Nie TO Abaca 

442 IF A€KC Jee) C= Tek OR AGHC RGR? > SER THEN 114 ELSE JéeaJeet+niin 

413 AGRC TER? = AGRO MER? 

444 NEXT KOA: AGecGas = Jee: CHANGE Aes TO Aes: 
FNCe$ = AGS: FNEND 


415 PRINT "TE = "3 TH 
124 GOTO 166 
999 END 


Lines 118 through 114 can be replaced by a single CVT$$ function 
statement at line 195 as shown in the sample code below. 


LISTNH 

4QG PRINT "TYPE THE INFUT STRING": > INPUT LINE Ae¢ 
165 T# = CVTESC RES, Feo 

445 PRINT "TE = "i TE 

42@ GOTO i186 

g99 END 


The value 7% in the CvT$$ function is the sum of 1%, 2%, and 4%. The 
CVTSS function with a value 7% causes the same results as the code of 
the user-defined function FNC6$. The following sample dialog shows 
the effect of the value 7% at line 195. 


TYPE THE INPUT STRING? DES: FILE EXT $186,106) 
1% = GEV: FILE. EXTC166, 168) 
TYPE THE INPUT STRING? “OC 
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The value 255% in the CVTS$ function at line 185 produces the results 
shown by the following sample dialog. 


TYPE THE INFUT STRING? GEM: PPLE, FST (ihe. 166) 
14 = DEV:FILE. EXT¢166, 166% 
TYPE THE INFUT STRING? “CO 


(The vaiue 255% can be replaced by -1% to produce the same results.) 
The following sample dialog shows the effect of the value 189% 
(134+43+83+16%+323+1288) . 


V4PE THE INPUT STRING? I Hel Fi GUOt Meth 
14 = I AM A GOOG MAN. 
TYPE THE INPUT STRING? 7C 


12.6 EXAMPLES OF RECORD I/O USAGE 


In Figure 12-1, the device KB: is opened with the default size 
(128 characters) buffer length by the OPEN statement at line 19. 


LISTNK 

16 OPEN "KB: " FOR GUTPUT AS FILE 4 

2@ FIELD #41. 418 AS Af, 16 AS BF, 1h AS CF 
30 LSET A#="1er45" 

46 RSET B#="e7590" 


54 RSET C#="VMRYS" 
6@ PUT #4. COUNT 24 
78 END 


READY 


Figure 12-1 
Record I/O Example #1 
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The FIELD statement at line 28 defines three 19-character segments 
of the buffer as A$, B$ and C$. LSET at Line 38 positions "12345" 
in the leftmost 5 of the first 10 characters of the buffer via the 
pointer AS. Similarly the second and third 19-character pieces of 
the buffer are set by lines 4 and 58. When run, this program 
generates: 


RUNHH 
12345 er eae VARS 
READY 


Note that no carriage return/line feed was output by the PUT state- 
ment. (The Monitor outputs a CR/LF sequence as the first part of the 
READY message.) 


Figure 12-2 is a program to move data from a file named 
"SNOOPY.BAS" in the system library (note the $ in the filename) onto 
the line printer. Both the line printer and the disk file buffers 
are initialized to 512 characters. The FIELD statements at lines 
49 and 58 set AS and BS to refer to these buffers. Data read at line 
6% is transferred to the line printer buffer by the LSET statement 
(RSET would also be acceptable in this one case, since both A$ and B$ 
are the same length) at line 7%. Then, at line 8%, this data is output 
to the line printer. The loop terminates on end-of-file on attempting 
to read past the last block of the SNOOPY.BAS file via the ON ERROR 
GOTO mechanism. 


LISTNH 
OPEN "“$SNQOFY. BAS" AS FILE 1 
ON ERROR GOTO 166 
OPEN "LP:" FOR GUTPUT AS FILE 2. RECORDSIZE S12 
FIELD #4, Si2 AS AF 
FIELD #2, 5412 AS BF 
GET #1 
LSET BS = AF 
PUT #2 


158 END 


READY 


Figure 12-2 
Record I/O Example #2 
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FIELD statements can be used to perform blocking and deblocking 
of records where appropriate, as in Figure 12-3. 


186 GET #2 ; 

116 FOR X=@ TO 420 STEP &@ 

12@ FIELD #2. K RS AF, SA AS BF 
e 


e 
188 NEXT K 
190 PUT #2 


Figure 12-3 
FIELD Statement Example 


Figure 12-4 illustrates the use of the CVT functions to store 
numerical data in compact form as strings of binary types. The tape 
punched by this program has each integer represented on two frames 
of tape. A similar program could be written to read this binary tape. 


16 DIM ASC9S) 
26 OPEN "PP:" FOR OUTPUT AS FILE 1, RECORDSIZE 20a 
3@ FIELD #4, @#I1 AS 2%, @ AS ACI) FOR T=@ To 99 


40 LSET ASCIKD = CVTHECIND FOR Ix=@% TO 99% 
58 PUT #1 

68 CLOSE 1 

939 END 


Figure 12-4 
CVT Function Example 
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12.7 THE XLATE FUNCTION 


The XLATE function is provided for use with Record I/O to trans- 
late a string from one storage code into another. For example, while 
reading a magtape file, it might be necessary to translate from EBCDIC 
code to ASCII code so that data could be processed by the PDP-11. The 
XLATE function is of the form: 


XLATE (<string1>,<string2>) 


For example: 


XS = XLATE (AS,BS) 


The first argument, <string1>, is the source string, the second argu- 
ment <string2>, is the table string; the string value returned by 
XLATE is called the target string. Characters are taken sequentially 
from the source string, and the value of each character (f@ to 255) 

is used as an index into the table string (that is, § means the first 
character of the table string, 1 means the second, etc.). The 
character value from the table string is appended to the target string 
unless the selected character in the table string has a value of @ 

or the table string is shorter than the index value. This means that 
the target string is equal to or shorter than the source string. 


For example, the following program removes all characters except 
"g" to "9" and changes the characters "8" and "9" into "A" and "B": 


LISTNH 

100 T# = "G@1224567AB" 

418 T$ = CHREC1“29+T¢ FOR Tk=Ge TO 47% 

142@ REM - LINE 14@ PUT @°S CORRESPONDING TO CODES @ TO 47 
438 INPUT S$ 'GET STRING TO TRANSLATE 
44@ PRINT KLATECS$, T#3 

45@ END 

READY 

RUNHH 

2 A2KKKZ4WWNOSEPES4 se] 

12340BA7654321 

READY 
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APPENDICES 


The following pages contain a summary of the 
BASIC-PLUS language, the commands described 
in the RSTS-11 System User's Guide, and error | 


‘messages. 


APPENDIX A 
BASIC-PLUS LANGUAGE SUMMARY 


A.1 SUMMARY OF VARIABLE TYPES 


Type 
Floating Point 
Integer 
Character String 


Floating Point 
Matrix 


Integer Matrix 


Character String 
Matrix 


Variable Name 


single letter 
optionally followed by a 
single digit 


any floating point variable 
name followed by a % character 


any floating point variable 
name followed by a $ character 


any floating point variable 
name followed by one or two 
dimension elements in 
parentheses 


any integer variable name 
followed by one or two dimen- 
sion elements in parentheses 


any character string variable 
name followed by one or two 
dimension elements in paren- 
theses 


A.2 SUMMARY OF OPERATORS 


Type 
Arithmetic 


Relational 


Logical 


String 


Matrix 


ae 


Operator 
unary minus 
exponentiation 
/ multiplication, division 
- addition, subtraction 


equals 
less than 
less than or equal to 
greater than r 

= greater than or equal to 
<> not equal to 
== approximately equal to 


NOT logical negation 

AND logical product 

OR logical sum 

XOR logical exclusive or 
IMP logical implication 
EQV logical equivalence 


+ concatenation 


+,- addition and subtraction 


of matrices of equal dimen- 


sions, one operator per 


statement 

* multiplication of con- 
formable matrices 

id scalar multiplication of 


a Matrix, see Section 7.5.1 


Examples 

A 

I 

x3 

BS 

D7% 

MS 

R1s$ 

S (4) E(5,1) 
N2(8) V8(3,3) 
A%(2) 1%(3,5) 


E3% (4) R2%(2,1) 


S$ (8,5) 
A2$(8) V1$ (4,2) 


Operates Upon 
numeric variables 
and constants 


string or 
numeric variables 
and constants 


relational ex- 
pressions composed 
of string or numeric 
elements, integer 
variables or integer 
valued expressions 


string constants 
and variables 


dimensioned vari- 
ables. See Sec- 
tion 7.6.1 for 
further details. 


A.3 SUMMARY OF FUNCTIONS 


Under the Function column, the functions is shown as: 


Y=function 


where the characters % and $ are appended to Y if the value returned 


is an integer or character string. 


A floating value (X), where specified, can always be replaced 


by an integer value. 


An integer value (N%) can always be replaced 


by a floating value (an implied FIX is done) except in the CVvTss 
and MAGTAPE functions (the symbol I% is used to indicate the neces- 


sity for an integer value). 


Type 


Mathematical 


Print 


String 


Function 


Y=ABS (X) 
Y=ATN (X) 


Y=COS (X) 


Y=EXP (X) 
Y=FIX (X) 


Y=INT (X) 
Y=LOG (X) 
Y=LOG19 (xX) 
Y=PI 
Y=RND 
Y=RND (X) 
Y=SGN (X) 
Y=SIN (X) 


Y=SQR (X) 
Y=TAN (X) 


Y%=POS (X%) 


YS=TAB (X%) 


¥%=ASCII (AS) 


Y$=CHR$ (X$%) 


YS=CVT$S (I$) 
YS=CVTFS (X) 
Y%=CVTS% (AS) 


Y=CVTSF (AS) 


Explanation 


returns the absolute value of X. 
returns the arctangent of X where X is 
in radians. 
returns the cosine of X where X is 
in radians. 
returns the value of etX, where e=2.71828. 
returns the truncated value of X, 
SGN (X) * INT (ABS (X) ) 
returns the greatest integer in X which 
is less than or equal to x, 
returns the natural logarithm of X, log Xx 
returns the common logarithm of x, log, 4X 
has a constant value of 3.14159 
returns a random number between @ and 1, 
returns a random number between @ and 1, 
returns the sign function of X, a value 
of 1 preceded by the sign of X 
returns the sine of X where X is in radians 
returns the square root of X 
returns the tangent of X where X is in 
radians 


returns the current position of the print 
head for I/O channel X, @ is the user's 
Teletype. (This value is imaginary for 
disk files.) 

moves print head to position X in the cur- 
rent print record, or is disregarded if 
the current position is beyond xX. (The 
first position is counted as §.) 


returns the ASCII value of the first char- 
acter in the string AS. 

returns a character string having the 
ASCII value of X. Only one character 
is generated. 

maps integer into 2-character string, see 
Section 12.5. 

maps floating-point number into 4- or 8- 
character string, see Section 12.5. 

maps first 2 characters of string AS into 
an integer, see Section 12.5. 

maps first 4 or 8 characters of string AS 
into a floating-point number. See Sec- 
tion 12.5. 
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Type 


String, 
cont'd. 


System 


Function 
YS = CVTS$(A$,18) 
YS = STRINGS 
(N13 ,N2$%) 


YS=LEFT (AS ,N%) 


YS=RIGHT (A$ ,N3%) 


YS$=MID (A$,N1%8,N2%) 


Y%=LEN (AS) 


Y%=INSTR(N1%,A$,BS$) 


YS=SPACES (N3%) 


YS=NUMS (N%) 


Y=VAL (A$) 


YS=XLATE (A$ ,BS$) 


YS=DATES (93) 


Explanation 


converts string A$ to string Y$ 
according to value of I%. See 
Section 12.5. 

creates string Y$ of length Nl and 
characters whose ASCII decimal value 


is N2. See Section 5.5. 
returns a substring of the string A$ 


from the first character to the Nth 
character (the leftmost N characters) 

returns a substring of the string A$ 
from the Nth to the last character; 
the rightmost characters of the strin 
Starting with the Nth character. 

returns a substring of the string A$ 
starting with the Nl and being N2 
characters long (the characters 
between and including the Nl 
to N1+N2-1 characters). 

returns the number of characters in the 
string A$, including trailing blanks. 

indicates a search for the substring 
BS within the string A$ beginning at 
character position Nl. Returns a 
value g if BS is not in A$, and the 
character position of BS if B$ is 
found to be in A$ (character posi- 
tion is measured from the start of 
the string). 

indicates a string of N spaces, used 
to insert spaces within a character 
string. 

indicates a string of numeric charac- 
ters representing the value of N as 
it would be output by a PRINT state- 


ment. For example: NUM$(1.9999) 
(space) 1(space) and NUMS (-1. 9 G92) 
-l(space). 

computes the numeric value of the 
string of numeric characters A$. 
If AS contains any character not 
acceptable as numeric input with 
the INPUT statement, an error re- 
sults. For example: 


VAL ("15") =15 


Hou 


translate A$ to the new string Y$ 
by means of the table string B§, 
see Section 12.7, 


returns the current date in the fol- 
lowing format: 


g2-Mar-71 


Type 


System, 
cont'd. 


Function 


Y$=DATES (N%) 


YS=TIMESS (@%) 


YS=TIMES (N%) 


Y=TIME (9%) 


Y=TIME (13) 


Y=TIME (23%) 


Y=TIME (33) 


Y=TIME (4%) 


Y¥%=STATUS 


Y¥%=BUFSIZ (N) 


Y%=LINE 


Y%=ERR 


Y%=ERL 


YS=SWAP3 (N3%) 


Explanation 


returns a character string correspond- 
to a calendar date as follows: 
N=(day of year)+ ((number of 
years since 1970) *1000] 


DATES (1) "91-Jan-79" 
DATES (125) "95-May-79" 


oi 


returns the current time of day as a 
character string as follows: 


TIMES (9) ="95:38 PM" 
or"17:39 : 


returns a string corresponding to the 
time at N minutes before midnight, 
for example: 


TIMES (1) "11:59 PM" or 23:59 
TIMES (1449) = "12:99 AM" or 69:99 


TIMES (721) "11:59 AM" or 11:59 


returns the clock time in seconds 
since midnight, as a floating point 
number. 

returns the central processor time 
used by the current job in tenths 
of seconds. 

returns the connect time (during which 
the user is logged into the system) 
for the current job in minutes. 

returns to Y the decimal number of 
kilo-core ticks (kct's) used by 
this job. See Section 8.8. 

returns to Y the decimal number of 
minutes of device time used by 
this job. See Section 8.8. 

returns to Y% the status of the 
most recently OPENED statement 
executed in the program. See 
Section 12.3.5. 

returns to Y% the buffer size of the 
device or file open on channel N. 
See Section 12.3.4. 

returns to Y% the line number of the 
statement being executed at the 
time of an interrupt. See Section 
4.5. 

returns value associated with the last 
encountered error if an ON ERROR 
GOTO statement appears in the pro- 
gram. See Section 8.4. 

returns the line number at which the 
last error occurred if an ON ERROR 
GOTO statement appears in the pro- 
gram. See Section 8.4.3. 

causes a byte swap operation on the 
two bytes in the integer variable 
NS. 


Type Function 


Y$=RAD$ (N%) 


Matrix MAT Y=TRN(X) 
MAT Y=INV(X) 


Y=DET 


Yt=NUM 


Y3=NUM2 


Input/Output Y%$=RECOUNT 


Explanation 


converts an integer value to a 3- 
character string and is used to con- 
vert from Radix-5@ format back to 
ASCII. See Appendix D. 


returns the transpose of the matrix 
X, see Section 7.6.2. 

returns the inverse of the matrix X, 
see Section 7.6.2. 

following an INV(X) function evalua- 
tion, the variable DET is equiva- 
lent to the determinant of X. 

following input of a matrix, NUM 
contains the number of rows input, 
or in the case of a one dimensional 
matrix, the number of elements 
entered. 

following input of a matrix, NUM2 
contains the number of elements 
entered in that row. 


returns the number of characters read 
following every input operation. 
Used primarily with non-file 
eet ae devices. See Section 


A.4 SUMMARY OF BASIC-PLUS STATEMENTS 


The following summary of statements available in the BASIC-PLUS 
language defines the general format for the statement as a line in a 
BASIC program. If more detailed information is needed, the reader is 
referred to the section(s) in the manual dealing with that particular 
statement. 


In these definitions, elements in angle brackets are necessary 
elements of the statement. Elements in square brackets are necessary 
elements of which the statement may contain one. Elements in braces 


are optional elements of the statement. 


Where the term line number ({line number}) is shown in braces, 


this statement can be used in immediate mode. 
The various elements and their abbreviations are described below: 
vartable or var Any legal BASIC variable as described in A.1 
or Section 2.5.2. 


line number Any legal BASIC line number described in 
Section 2.2. 


expression or ex Any legal BASIC expression as described in 
Section 2.5. 


message Any combination of characters. 

econdtitton or cond Any logical condition as described in Sec- 
tion 3.5. 

constant Any acceptable integer constant (need not 


contain a % character). 
argument(s) oY arg Dummy variable names. 
statement Any legal BASIC-PLUS statement. 


string Any legal string constant or variable as 
described in Section 5.1. 


proteetton Any legal protection code as described in 
Section 9.1. 


value (s) Any floating point, integer, or character 
string constant. 


list The legal list for that particular statement. 

dimenston(s) One or two dimensions of a matrix, the maxi- 
mum dimension(s) for that particular state- 
ment. 


Manual 


Statement Formats and Examples Section 
REM 
{line number} REM <message> 3.1 


{line number}{<statement>}!<message> 
1g REM THIS IS A COMMENT 
15 PRINT !PERFORM A CR/LF 


LET 
{line number} {LET}<var>{,<var>,<var>...} = <exp> 3.2 
55 LET A=49: B=22 
69 B,C,A=4.2 !MULTIPLE ASSIGNMENT 
DIM 


Pp DIiM<var(dimension(s}j> 3. 
, 


é 6.2 
1g DIM A(2@), BS(5,18), C%(45) 7.1 
1 


line number DIM #<eonstant>,<var(dimenston(s))>=<constant> ll. 
75 DIM #4, AS (109)=32,B(59,592) 


RANDOMIZE 3.7.2 
tine number RANDOM{IZE} 
55 RANDOMIZE 


78 RANDOM 
IF-THEN, IF-GOTO THEN<statement> 
line number IF <cond> Es nunber>| 3.5 
GOTO<Zline number> 
55 IF A>B OR B>C THEN PRINT "NO" 
6@ IF FNA(R)= B THEN 259 
95 IF L<xXt2 AND L<>¢g GOTO 345 
IF-THEN-ELSE 8.5 


THEN<statement> 
line number IF <eond> 


THEN<Zine number> ELSE<statement> 
GOTO<line number> ELSE<line number> 


38 IF B=A THEN PRINT "EQUAL" ELSE PRINT "NOT EQUAL" 
58 IF A>N THEN 299 ELSE PRINT A 
75 IF B==R THEN STOP ELSE 89 


FOR 
line number FOR <var>= <exp>TO <exp> {STEP<exp>} 3.6.1 


20 FOR I=2 TO 4@ STEP 2 
55 FOR N=A TO A+R 


FOR-WHILE, FOR-UNTIL WHILE 8.6 
line number FOR <var> = <erp> {STEP<exp>} UNTIL, | <cond> 
84 FOR I = 1 STEP 3 WHILE I<x 
74 FOR N = 2 STEP 4 UNTIL N>A OR N=B 
g5 FOR B= 1 UNTIL B>l1g 
NEXT 3.6.1 
line number NEXT <var> 
25 NEXT I 
68 NEXT N 
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Statement Formats and Examples Section 
DEF, single line 3.7.3 
line number DEF FN<var>(arg) =<exp(arg)> 5.5.1 
28 DEF FNA(X,Y,Z)=SQR(Xt2+Y+2+Z+t2) 6.4 


DEF, multiple line 


line 


line 
line 


GOTO 


line 


ON-GOTO 
line 


GOSUB 
line 


ON-GOSUB 
line 


RETURN 
Line 


CHANGE 


{line 


OPEN 


{line 


CLOSE 
Tline 


READ 


line 


number DEF FN<var>(arg) 8.1 
<statements> 
number FN<var>=<exp> 
number FNEND 
19 DEF FNF(M) {FACTORIAL FUNCTION 
20 $F M=1 THEN FNF=1 ELSE FNF=M*FNF (M-1) 


38 FNEND 
3.4 
number GOTO <line number> 
198 GOTO 59 
number ON <exp> GOTO <list of line numbers> 8.2 
75 ON X GOTO 95, 159, 45, 269 
number GOSUB <line number> 3.8.1 
98 GOSUB 299 
number ON <exp> GOSUB <list of line numbers> 8.3 
85 ON FNA(M) GOSUB 29%, 259, 49%, 375 
number RETURN 3.8.2 
375 RETURN 
5.2 
<array name> Bee var>™ 
number} CHANGE| (O77) | ss aay i 
25 CHANGE A$ TO X 
78 CHANGE M TO R$ 
75 CHANGE B TO BS 
9.2 
. NPUT 9.2.1 
number } OPEN<s tring>{For(sNr Or JAS FILE <exp> 9.2.2 
{,RECORDSIZE<exp>}{,CLUSTERSIZE <eaxp>}{,MODE <exp>} 
19 OPEN "PP:" FOR OUTPUT AS FILE Bl 
28 OPEN "FOO" AS FILE 3 
38 OPEN "DT4:DATA.TR" FOR INPUT AS FILE 19 9.3 
number} CLOSE <list of exp> 
199 CLOSE 2 
255 CLOSE 19, 4, Nl 
3.3.1 
5.3 
number READ <list of vartables> 6.3 
25 READ A, BS, C%, Fl, R2, B(25) 10.1 


Statement Formats and Examples 


DATA 
line number 
399 
RESTORE 
line number 
125 
PRINT 
{Zine number} 
25 
75 
45 
PRINT USING 
{line number} 
54 
55 
56 
INPUT 
Tline number} 
25 
55 
INPUT LINE 
{line number} 
4g 
75 
NAME-AS 
{line number} 
455 
276 
KILL 
{line number} 
45 


ON ERROR GOTO 
line number 
1g 
525 
526 


RES UME 
ine number 


1999 
655 


CHAIN 

"Line number 
375 
599 
626 


Section 
3.3.1 
DATA <list of values> 5.3 
DATA 4.3, "STRING",85,49,75.94,19 6.3 
3.3.1 
RESTORE 10.2 
RESTORE 
3.3.2 
5.4 
PRINT{{#<exp>, }<list>} 6.3 
PRINT !GENERATES CR/LF 10.3 
PRINT "BEGINNING OF OUTPUT" ;1I,A*I 10.3.1 
PRINT #4,"OUTPUT TO DEVICE"FNM(A)+2;B;A 10.3.2 
PRINT {#<exp>, }USING <string>, <list> 10.3.3 
PRINT USING "##.##",A 
PRINT #3, USING"\\###.## \\##ttt+","A=",A,"B=",B 
PRINT #7, USING BS,A,B,C 
3633 
INPUT {#<exrp>, }<list> 5.3 
INPUT "TYPE YOUR NAME ",AS 6.3 
INPUT #8, A, N, BS 10.4 
10.4.1 
5.3 
INPUT LINE {#<exp>,} <string> 
INPUT LINE R$ 
INPUT LINE #1, ES 
NAME <string> AS <string> 9.5 
NAME "NONAME" AS "FILE1<48>" 
NAME "DT4:MATRIX" AS "MATA1<48>" 
8.4 
KILL <string> 
KILL “NONAME" 
ON ERROR GOTO {<Zine number>} 
ON ERROR GOTO 599 
ON ERROR GOTO !DISABLES ERROR ROUTINE 
ON ERROR GOTO 9 !DISABLES ERROR ROUTINE 
8.4.1 
RESUME {<Zine number>} 
RESUME !OR RESUME @ ARE EQUIVALENT 
RESUME 299 
CHAIN <string> {<exp>} 9.6 


Manual 


CHAIN "PROG2" 
CHAIN "PROG3" 75 
CHAIN "PROG3" A 


Manual 


Statement Formats and Examples Section 
STOP 3.9 
tine number STOP 
75 STOP 
END 3.9 
line number END 
545 END 
Matrix Statements 
MAT READ 7.2 
line number MAT READ <list of matrtces> 
55 DIM A(29), BS(32), C%(15,19) 
98 MAT READ A, BS$(25), C% 
MAT PRINT 7.3 
{Tine number} MAT PRINT{#<exp>,} <matrix name> 
1@ DIM A (29), B(15,29) 
99 MAT PRINT A; !PRINT 19*1@ MATRIX, PACKED 


95 MAT PRINT B(19,5), !PRINT 19*5 MATRIX, FIVE 


!ELEMENTS PER LINE 


97 MAT PRINT #2, A; {PRINT ON OUTPUT CHANNEL 2 
MAT INPUT : 7.4 
{Zine number} MAT INPUT{#<exp>,} <list of matrices> 
1g DIM BS$(4M), F1%(35) 
28 OPEN "DT3:FOO" FOR INPUT AS FILE 3 
38 MAT INPUT #3, B4, F1% 
MAT Initialization 7.5 
ZER 
{Zine number} MAT <matriz name>=|CON|{dimension(s)} 
D 
19 DIM B(15,19), A(1g), C(5) 
15 MAT C% = CON {ALL ELEMENTS OF C%(I)=1 
20 MAT B= IDN (19,19) LIDENTITY MATRIX 19*19 
95 MAT B = ZER(N,M) !CLEARS AN N BY M MATRIX 
Statement Modifiers (can be used in immediate mode) 
if Oc7.1 
<statement> IF <condttion> 
1g PRINT X IF X<o"”g 
UNLESS 
<statement> UNLESS <eondttion> 8.7.2 
45 PRINT A UNLESS A=9 
FOR ; 8.7.3 
<statement> FOR <var> = <exp> TO <exp>{STEP<eaxp>} 
75 LET BS(I) = "PDP-11" FOR I = 1 TO 25 
88 READ A(I) FOR I=2 TO 8 STEP 2 
WHILE 8.7.4 


<statement> WHILE <conditton> 
1@ LET A(I) = FNX(I) WHILE I<45.5 


Statement Formats and Examples 


Manual 
Section 
UNTIL 8.7.5 
<statement> UNTIL <econditton> 
115 IF B § THEN A(I)=B UNTIL 155 
System statements 
<Line number> SLEEP <expresston> 8.8 
168 SLEEP 29 IDISMISS JOB FOR 28 SEC. 
<line number> WAIT <expresston> 8.8 
525 WATT A&+5 IWATIT A%+5 SEC. FOR INPUT 
Record I/O Statements 
<Line number> LSET<string var>{,<string var>}=<string> 12.4.3 
96 LSET BS="xYzZ" 
<Line number> RSET<string var>{,<string var>}=<string> 12.4.3 
256 RSET CS="67896" 
<Line number> FIELD#<expr>,<expr>AS<string var>{,<expr>AS<string var>} 
75 FIELD#2%,10% AS AS, 28% AS BS 12.4.2 
<Line number> GET#<expr>{, RECORD<expr>} 12.3 
1§@ GET#1%,RECORD 99% 
<line number> PUT#<expr>{,RECORD<expr>}{,COUNT<expr>} 12.3 
566 PUT#1%,COUNT 89% 
<Line number> UNLOCK#<expr> 10.5.1 
7698 UNLOCK #3% 


Command 


APPEND 


ASSIGN 


ATTACH 


BYE 


CAT 
CATALOG 


CCONT 


COMPILE 


CONT 


DEASSIGN 


DELETE 


APPENDIX B 


BASIC-PLUS COMMAND SUMMARY 


Section in 
RSTS-11 System 


Explanation User's Guide 
Used to include contents of a previously 2.4.3 


saved source program in current program. 


Used to reserve an I/O device for the use 2.6.3 
of the individual issuing the command. The 

specified device can then be given commands 

only from the job which issued the 

ASSIGN. Also establishes a logical name 

for a device, establishes an account for 

the @ character, and establishes a default 

protection code. 


Attaches a detached job to the current 4.1 
terminal. 
Indicates to RSTS that a user wishes to 2.1.3 


leave the terminal. Closes and saves any 
files remaining open for that user. 


Returns the user's file directory. Unless 26562 
another device is specified following the 

term CAT or CATALOG, the disk is the 

assumed device. 


For privileged users. Same as CONT command, 2.2.9 
but detaches job from terminal. 


Allows the user to store a compiled version of 2.3.3 
his BASIC program. The file is stored on disk 

with the current name and the extension .BAC. 

Or, a new file name can be indicated and the 

extension .BAC will still be appended. 


Allows the user to continue execution of the 2.2.8 


program currently in core following the 
execution of a STOP statement. 


Used to release the specified device for use 2.6.4 
by others. If no particular device is speci- 2.7 
fied, all devices assigned to that terminal 

are released. An automatic DEASSIGN is per- 

formed when the BYE command is given. Also 

releases any logical name for a device. 


Allows the user to remove one or more lines 22205 
from the program currently in core. Follow- 

ing the word DELETE the user types the line 

number of the single line to be deleted or 

two line numbers separated by a dash (-) 

indicating the first and last line of the 

section of code to be removed. Several 

single lines or line sections can be indi- 

cated by separating the line numbers, or 

line number pairs, with a comma. 


B-1 


Section in 
RSTS-11 System 


Command Explanation User's Guide 
HELLO Indicates to RSTS that a user wishes to log 2.1.2 


onto the system. Allows the user to input 
project-programmer number and password. 
Also attaches a detached job to the current 
terminal or changes accounts without having 
to log off the system. 


KEY Used to re-enable the echo feature on the user 2.6.2 
terminal following the issue of a TAPE com- 
mand. Enter with LINE FEED or ESCAPE key. 


LENGTH Returns the length of the user's current 2 Da 
program in core, in 1K increments. 


LIST Allows the user to obtain a printed listing 2.2.4 
at the user terminal of the program cur- 
rently in core, or one or more lines of that 
program. The word LIST by itself will cause 
the listing of the entire user program. 

LIST followed by one line number will list 
that line; and LIST followed by two line 
numbers separated by a dash (-) will list the 
lines between and including the lines 
indicated. Several single lines or line 
sections can be indicated by separating the 
line numbers, or line number pairs, with a 


comma . 
LISTNH Same as LIST, but does not print header con- 2.2.4 
taining the program name and current data. 
LOGIN Same as HELLO on Version 5 (RSTS/E) systems. 4.1 
NEW Clears the user's area in core and allows the 2.2.1 


user to input a new program from the terminal. 
A program name can be indicated following the 
word NEW or when the system requests it. 


OLD Clears the user's area in core and allows the 2.4.2 
user to recall a saved program from a storage 
device. The user can indicate a program name 
following the word OLD or when the system 
requests it. If no device name is given, the 
file is assumed to be on the system disk. A 
device specification without a filename will 
cause a program to be read from an input-only 
device (such as high-speed reader, card 


reader). 
REASSIGN Transfers control of a device to another job. 2.6.5 
RENAME Causes the name of the program currently in 2.2.6 


core to be changed to the name specified after 
the word RENAME. 


REPLACE Same as SAVE, but allows the user to substitute 2.4.7 
a new program for an old program with the same 
name, erasing the old program. 


Command 


RUN 


RUNNH 


SAVE 


SCALE 


TAPE 


UNSAVE 


Section in 
RSTS-11 System 


Explanation User's Guide 
Allows the user to begin execution of the pro- 2.3.1 


gram currently in core. The word RUN can be 
followed by a file name in which case the file 
is loaded from the system disk, compiled (if 
necessary), and run; alternatively, the device 
and file name can be indicated if the file is 
not on the system disk. A device specification 
without a file name will cause a program to be 
read from an input only device (such as high- 
Speed reader, card reader). 


Causes execution of the program currently in 2.3.1 
memory but header information containing the 

program name and current data is not printed. 

If a filename is used, the command is exe- 

cuted as if no filename were given. 


Causes the program currently in core to be 2.4.1 
saved on the system disk under its current 

file name with the extension .BAS. Where 

the word SAVE is followed by a file name or 

a device and a file name, the program in core 

is saved under the name given and on the 

device specified. A device specification 

without a file name will cause the program 

to be output to any output only device (line 

printer, high-speed punch). 


Sets the scale factor to a designated value 2.8 
or prints the value(s) currently in effect 
if no value is designated. 


Used to disable the echo feature on the user 2.6.1 
terminal while reading paper tape via the low- 
speed reader. 


The word UNSAVE is followed by the file name 2.4.6 
and, optionally, the extension of the file to 

be removed. The UNSAVE command cannot remove 

files without an extension. If no extension 

is specified, the source (.BAS) file is deleted. 

If no device is specified, the disk is assumed. 


Section in 
RSTS-11 System 
Command Explanation User's Guide 


Special Control Character Summary 


CTRL/C Causes the system to return to BASIC com- 3.5 
mand mode to allow for issuing of further 
commands or editing. Echoes on terminal as 


tc. 

CTRL/O Used as a switch to suppress/enable output 3.7 
of a program on the user terminal. Echoes as 
tO. 

CTRL/Q When generated by a device on which a CTRL/S 3.10 


has interrupted output, causes computer to 
resume output at the next character. 


CTRL/S When generated by a device for which STALL 3.10 
characteristics are set, interrupts computer 
output on the device until either CTRL/Q or 
another character is generated. 


CTRL/U Deletes the current typed line, echoes as [{U 3.6 
and performs a carriage return/line feed. 

CTRL/Z Used as an end-of-file character. 3.9 

ESCape or Enters a typed line to the system, echoes on 3.2 

ALT MODE the user terminal as a $ character and does 

Key not cause a carriage return/line feed. 

LINE FEED Used to continue the current logical line on 3.3 

Key an additional physical line. Performs a 


line feed/carriage return operation. 


RETURN Enters a typed line to the system, results in 3.1 
Key a carriage return/line feed operation at the 
user terminal. 


RUBOUT Deletes the last character typed on that 3.4 
Key physical line. Erased characters are shown 
on the teleprinter between back slashes. 


TAB or Performs a tabulation to the next of nine tab 3.8 
CTRL/I stops (eight spaces apart) which form the 
terminal printing line. 


APPENDIX C 


ERROR MESSAGE SUMMARY 


Wherever possible, RSTS follows an error message with the phrase 
AT LINE xxxx 


where xxxx is the line number of the statement which caused the error. 


For example: 


1g TALK 
ILLEGAL VERB AT LINE 19 
READY 


The additional message is not printed when no line number can be as- 


sociated with the error. 


TALK 
WHAT? 


READY 


An (SPR) in the description of any error message in this Appendix 
indicates an error which should never be seen by a user. If such a 
message is received, the user should document how he obtained the error 
and file a Software Performance Report with DEC, including the perti- 


nent output. 
C.1 USER RECOVERABLE ERRORS 


A (C) in the description of the error message indicates that pro- 
gram execution continues, following printing of the error message, 
if an ON ERROR GOTO statement is not present. Normally, execution 
terminates on an error condition, the error message is printed, and 
the system prints READY. The ERR column gives the value of the ERR 


variable (see Section 8.4). 


ERR Message Printed Meaning 
1 BAD DIRECTORY FOR DEVICE The directory of the device refer- 


enced is in an unreadable format. 


ERR Message Printed Meaning 


2 ILLEGAL FILE NAME The filename specified is not accept- 
able. It contains unacceptable char- 
acters or the filename specification 
format has been violated. 


3 ACCOUNT OR DEVICE IN USE Removal or dismounting of the account 
or device cannot be done since one 
or more users are currently using it. 


4 NO ROOM FOR USER ON DEVICE Storage space allowed for the current 
user on the device specified has been 
used or the device as a whole is too 
full to accept further data. 


5 CAN'T FIND FILE OR ACCOUNT The file or account number specified 
was not found on the device specified. 


6 NOT A VALID DEVICE Attempt to use an illegal or nonexis- 
tent device specification. 


7 I/O CHANNEL ALREADY OPEN An attempt was made to open one of 
the twelve I/O channels which had 
already been opened by the program. 
(SPR) 


8 DEVICE NOT AVAILABLE The device requested is currently 
reserved by another user. 


9 I/O CHANNEL NOT OPEN Attempt to perform I/O on one of the 
twelve channels which has not been 
previously opened in the program. 


10 PROTECTION VIOLATION The user was prohibited from perform- 
ing the requested operation because 
the kind of operation was illegal 
(such as input from a line printer) 
or because the user did not have the 
privileges necessary (such as delet- 
ing a protected file). 


11 END OF FILE ON DEVICE Attempt to perform input beyond the end 
of a data file; or a BASIC source fileis 
called into memory and is found to con- 
tain no END statement. 


12 FATAL SYSTEM I/O FAILURE An I/O error has occurred on the sys- 
tem level. The user has no guarantee 
that the last operation has been per- 
formed. (SPR) 


13 USER DATA ERROR ON DEVICE One or more characters may have been 
transmitted incorrectly due to a par- 
ity error, bad punch combination on 
a card, or similar error. 


14 DEVICE HUNG OR WRITE LOCKED User should check hardware condition 
of device requested. Possible causes 
of this error include a line printer 
out of paper or high-speed reader 
being off-line. 


ERR 
15 


16 


17 


18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


Message Printed 
KEYBOARD WAIT EXHAUSTED 


NAME OR ACCOUNT NOW EXISTS 


TOO MANY OPEN FILES ON UNIT 


ILLEGAL SYS() USAGE 


DISK BLOCK IS INTERLOCKED 


PACK IDS DON'T MATCH 


DISK PACK IS NOT MOUNTED 
DISK PACK IS LOCKED OUT 
ILLEGAL CLUSTER SIZE 


DISK PACK IS PRIVATE 


DISK PACK NEEDS 'CLEANING' 


FATAL DISK PACK MOUNT ERROR 


I/O TO DETACHED KEYBOARD 


PROGRAMMABLE tC TRAP 


CORRUPTED FILE STRUCTURE 


Meaning 
Time requested by Wait statement 


has been exhausted with no input re- 
ceived fromthe specified keyboard. 


An attempt was made to rename a 
file with the name of a file which 
already exists, or an attempt was 
made by the system manager to in- 
sert an account number which is 
already within the system. 


Only one open DECtape output file 
is permitted per DECtape drive. 
Only one open file per magtape 
drive is permitted. 


Illegal use of the SYS system func- 
tion. 


The requested disk block segment 
is already in use (locked) by some 
other user. 


The identification code for the 
specified disk pack does not match 
the identification code already on 
the pack. 


No disk pack is mounted on the 
specified disk drive. 


The disk pack specified is mounted 
but temporarily disabled. 


The specified cluster size is unac- 
ceptable. 


The current user does not have ac- 
cess to the specified private disk 
pack. 


Non-fatal disk mounting error; use 
the CLEAN operation in UTILTY. 
Fatal disk mounting error. Disk can- 
not be successfully mounted. 


I/O was attempted to a hung up 
dataset or to the previous, but now 
detached, console keyboard for the 
job. 


ON ERROR-GOTO subroutine was entered 
through a program trapped CTRL/C. 
See a description of the SYS system 
function. 


Fatal error in CLEAN operation. 


ERR 


30 


31 


32 


33 


34 


35 


36 


37 


38 


39 


40 


Message Printed 
DEVICE NOT FILE STRUCTURED 


ILLEGAL BYTE COUNT FOR I/O 


NO ROOM AVAILABLE FOR FCB 


UNIBUS TIMEOUT FATAL TRAP 


RESERVED INSTRUCTION TRAP 


MEMORY MANAGEMENT VIOLATION 


SP (R6) STACK OVERFLOW 


DISK ERROR DURING SWAP 


MEMORY PARITY FAILURE 


MAGTAPE SELECT ERROR 


MAGTAPE RECORD LENGTH 
ERROR. 


Meaning 


An attempt is made to access a de- 
vice, other than a disk, DECtape, 

or magtape device, as a file- 
structured device. This error 
occurs, for example, when the user 
attempts to gain a directory listing 
of a non-directory device. 


The buffer size specified in the 
RECORDSIZE option of the OPEN 
statement or in the COUNT option 
of the PUT statement is not a 
multiple of the block size of the 
device being used for I/O, or is 
illegal for the device. 


When the user accesses a file under 
programmed control in RSTS-1l, a 
system control structure called an 
FCB requires one small buffer and 
one small buffer is not available 
for the FCB. 


This hardware error occurs when 

an attempt is made to address 
nonexistent memory or an odd address 
using the PEEK function. An 
occurrence of this error message 

in any other case is cause for an 
SPR. 


An attempt is made to execute an 
illegal or reserved instruction 
or an FPP instruction when floating 
point hardware is not available. 


This hardware error occurs when an 
illegal Monitor address is specified 
using the PEEK function. Genera- 
tion of the error message in situa- 
tions other than using PEEK is cause 
for an SPR. 


An attempt to extend the hardware 
stack beyond its legal size is 
encountered. (SPR) 


A hardware error occurs when a 
user's job is swapped into or out 
of memory. The contents of the 
user's job area are lost but the 
job remains logged into the system 
and is reinitialized to run the 
NONAME program. 


A parity error was detected in the 
memory occupied by this job. 


When access to a magtape drive was 
attempted, the selected unit was 
found to be off line. 


When performing input from magtape, 
the record on magtape was found to 
be longer than the buffer designated 
to handle the record. 


ERR 
41 


42 


43 


44 
45 


46 


47 


48 


49 


50 


51 


52 


53 


54 


55 


Message Printed 
NO RUN-TIME SYSTEM 


VIRTUAL BUFFER TOO LARGE 


VIRTUAL ARRAY NOT ON DISK 


MATRIX OR ARRAY TOO BIG 


VIRTUAL ARRAY NOT YET OPEN 


ILLEGAL I/O CHANNEL 


LINE TOO LONG 


FLOATING POINT ERROR 


ARGUMENT TOO LARGE IN EXP 


DATA FORMAT ERROR 


INTEGER ERROR 


ILLEGAL NUMBER 


ILLEGAL ARGUMENT IN LOG 


IMAGINARY SQUARE ROOTS 


SUBSCRIPT OUT OF RANGE 


Meaning 


Reserved. 


Virtual core buffers must be 
512 bytes long. 


A non-disk device is open on the 
channel upon which the virtual 
array is referenced. 


In-core array size is too large. 


An attempt was made to use a 
virtual array before opening the 
corresponding disk file. 


Attempt was made to open a file 
on an I/O channel outside the 
range of the integer numbers 1 
to 12. 


Attempt to input a line longer 

than 255 characters (which includes 
any line terminator). Buffer 
overflows. 


Attempt to use a computed floating 
point number outside the range 

| 1E-38|<n<|1E38| excluding zero. 
If no transfer to an error 
handling routine is made, zero is 
returned as the floating point 
value. (C) 


Acceptable arguments are within the 
approximate range ~89<arg<+88, The 
value returned is zero. ([(C) 


A READ or INPUT statement detected 
data in anillegal format. For 
example, 1..2 is an improperly 
formed number, and 1.3 is an impro- 
perly formed integer, and X" is an 
illegal string. (C) 

Attempt to use a computed integer 
outside the range ~32767<n<32767. 
If no transfer to an error handling 
routine is made, zero is returned 
as the integer value. (C) 


Integer or floating point overflow 
or underflow. 


Negative or zero argument to log 
function, Value returned is the 
argument as passed to the function. 
(C) 


Attempt to take square root of a 
number less than zero. The value 
returned is the square root of the 
absolute value of the argument. (C) 


Attempt to reference an array ele- 
ment beyond the number of elements 
created for the array when it was 

dimensioned. 


ERR Message Printed 

56 CAN'T INVERT MATRIX 

57 OUT OF DATA 

58 ON STATEMENT OUT OF RANGE 
59 NOT ENOUGH DATA IN RECORD 
60 INTEGER OVERFLOW, FOR LOOP 
61 DIVISION BY g 

C.2 NON-RECOVERABLE ERRORS 


Message Printed 


ARGUMENTS DON'T MATCH 


BAD LINE NUMBER PAIR 


BAD NUMBER IN PRINT-USING 


CAN'T COMPILE STATEMENT 


CAN'T CONTINUE 


CATASTROPHIC ERROR 


DATA TYPE ERROR 


Meaning 


Attempt to invert a singular or 
nearly singular matrix. 


The DATA list was exhausted and a 
READ requested additional data. 


The index value in an ON-GOTO or 
ON-GOSUB statement is less than one 
or greater than the number of line 
numbers in the list. 


An INPUT statement did not find 
enough data in one line to satisfy 
all the specified variables. 


The integer index in a FOR loop 
attempted to go beyond 32766 or 
below -32766. 


Attempt by the user program to 
divide some quantity by zero. 
no transfer is made to an error 
handler routine, a @ is returned 
as the result. (C) 


If 


Meaning 


Arguments in a function call do not 
match, in number or in type, the 
arguments defined for the function. 


Line numbers specified in a LIST 
or DELETE command were formatted 
incorrectly. 


Format specified in the PRINT- 
USING string cannot be used to 
print one or more values. 


Program was stopped or ended ata 
spot from which execution cannot 
be resumed. 


The user program data structures 
are destroyed. This normally indi- 
cates a BASIC~PLUS malfunction and, 
if reproducible, should be reported 
to DEC on a Software Performance 
Report form (SPR). 


Incorrect usage of floating-point, 
integer, or character string for- 
Mat variable or constant where 
some other data type was necessary. 


Message Printed 


DEF WITHOUT FNEND 


END OF STATEMENT NOT SEEN 


EXECUTE ONLY FILE 


EXPRESSION TOO COMPLICATED 


FIELD OVERFLOWS BUFFER 


FILE EXISTS-RENAME/REPLACE 


FNEND WITHOUT DEF 


FNEND WITHOUT FUNCTION CALL 


FOR WITHOUT NEXT 


ILLEGAL CONDITIONAL CLAUSE 


ILLEGAL DEF NESTING 


ILLEGAL DUMMY VARIABLE 


ILLEGAL EXPRESSION 


Meaning 


A second DEF statement was encoun- 
tered in the processing of a user 
function without an FNEND state- 
ment terminating the first user 
function definition. 


Statement contains too many ele- 
ments to be processed correctly. 


Attempt was made to add, delete or 
list a statement in a compiled 
(.BAC) format file. 


This error usually occurs when 
parentheses have been nested too 
deeply. The depth allowable is 
dependent on the individual 
expression. 


Attempt to use FIELD to allocate 
more space than exists in the 
specified buffer. 


A file of the name specified in a 
SAVE command already exists. In 
order to save the current program 
under the name specified, use 
REPLACE, or RENAME followed by 
SAVE. 


An FNEND statement was encountered 
in the user program without a 
previous DEF statement being seen. 


A FNEND statement was encountered 
in the user program without a 
previous function call having been 
executed. 


A FOR statement was encountered in 
the user program without a corre- 
sponding NEXT statement to terminate 
the loop. 


Incorrectly formatted conditional 
expression. 


The range of one function definition 
crosses the range of another 
function definition. 


One of the variables in the dummy 
variable list of a user-defined 
function is not a legal variable 
name. 


Double operators, missing operators, 
mismatched parentheses, or some 
similar error has been found in an 
expression. 


Message Printed Meaning 


ILLEGAL FIELD VARIABLE The FIELD variable specified is 
unacceptable. 

ILLEGAL FN REDEFINITION Attempt was made to redefine a user 
function. 

ILLEGAL FUNCTION NAME Attempt was made to define a func- 


tion with a function name not sub- 
scribing to the established 
format. 


ILLEGAL 


ILLEGAL 


ILLEGAL 


ILLEGAL 


ILLEGAL 


ILLEGAL 


ILLEGAL 


INCONSISTENT FUNCTION USAGE 


INCONSISTENT SUBSCRIPT USE 


Message Printed 
IF STATEMENT 


IN IMMEDIATE MODE 


LINE NUMBER(S) 


MAGTAPE() USAGE 


MODE MIXING 


STATEMENT 


SYMBOL 


VERB 


K OF CORE USED 


LITERAL 


STRING NEEDED 


MATRIX DIMENSION ERROR 


MATRIX OR ARRAY WITHOUT DIM 


MAXIMUM CORE EXCEEDED 


MISSING SPECIAL FEATURE 


Meaning 


Incorrectly formatted IF statement. 


User issued a statement for execu- 
tion in immediate mode which can 
only be performed as part of a pro- 
gram, 


Line number reference outside the 
range 1<n<32767, 


Improper use of the MAGTAPE function. 


String and numeric operations cannot 
be mixed. 


Attempt was made to execute a state- 
ment that did not compile without 
errors. 


An unrecognizable character was en- 
countered. For example, a line con- 
sisting of a # character. 


The BASIC verb portion of the state- 
ment cannot be recognized. 


A function is being redefined in a 
manner inconsistent in the number or 
type of arguments with one or more 
calls to that function existing in 
the program. 


A subscripted variable is being used 
with a different number of dimensions 
from the number with which it was 
originally defined. 


Message printed by LENGTH command, 
preceded by the appropriate number 
describing the user program currently 
in core to the nearest 1K. 


A variable name was used where a 
numeric or character string was 
necessary. 


Attempt was made to dimension a 
matrix to more than two dimensions, 
Or an error was made in the syntax 
of a DIM statement. 


A matrix or array element was ref- 
erenced beyond the range of an 
implicitly dimensioned matrix. 


User program grew to be too large 
to run or compile in the area of 
core assigned to each user at the 
given installation. 


User program employs a BASIC-PLUS 
feature not present on the given 
installation. 


Message Printed 


MODIFIER ERROR 


NEXT WITHOUT FOR 


NO LOGINS 


NOT A RANDOM ACCESS DEVICE 


NOT ENOUGH AVAILABLE CORE 


NUMBER IS NEEDED 


1 OR 2 DIMENSIONS ONLY 


ON STATEMENT NEEDS GOTO 


PLEASE SAY HELLO 


PLEASE USE THE RUN COMMAND 


PRINT-USING BUFFER OVERFLOW 


PRINT-USING FORMAT ERROR 


PROGRAM LOST-SORRY 


REDIMENSIONED ARRAY 


RESUME AND NO ERROR 


Meaning 


Attempt to use one of the statement 
modifiers (FOR, WHILE, UNTIL, IF, 
or UNLESS) incorrectly. 


A NEXT statement was encountered in 
the user program without a previous 
FOR statement having been seen. 


Message printed if the system is 
full and cannot accept additional 
users or if further logins are dis- 
abled by the system manager. 


Attempt to perform random access I/O 
to a non-random access device. 


The already compiled user program is 
too large to run in the area of core 
assigned to each user at the given 
installation. 


A character string or variable name 
was used where a number was necessary. 


Attempt was made to dimension a matrix 
to more than two dimensions. 


A statement beginning with ON does 
not contain a GOTO or GOSUB clause. 


User not logged into the system has 
typed something other than a legal, 
logged-out command to the system. 


A transfer of control (as in a GOTO, 
GOSUB or IF-GOTO statement) cannot 
be performed from immediate mode. 


Format specified contains a field too 
large to be manipulated by the PRINT- 
USING statement. 


An error was made in the construction 
of the string used to supply the out- 
put format in a PRINT-USING statement. 


A fatal system error has occurred 
which caused the user program to be 
lost. 


Usage of an array or matrix within 
the user program has caused BASIC- 
PLUS to redimension the array im- 
plicitly. 


A RESUME statement was encountered 
where no error had occurred to cause 
a transfer into an error handling 
routine via the ON ERROR-GOTO state- 
ment. 


c-10 


Message Printed Meaning 


RETURN WITHOUT GOSUB RETURN statement encountered in the 
user program without a previous 
GOSUB statement having been executed. 


SCALE FACTOR INTERLOCK An attempt was made to execute a pro- 
gram or source statement with the cur- 
rent scale factor. The program executes 
but the system uses the scale factor of 
the program in memory. Use REPLACE and 
OLD or recompile the program to execute 
with the current scale factor. 


STATEMENT NOT FOUND R 
the program. 
STOP STOP statement was executed. The 


user can usually continue program 
execution by typing CONT and the 


RETURN key. 

STRING IS NEEDED A number or variable name was used 
where a character string was neces- 
sary. 

SYNTAX ERROR BASIC~PLUS statement was incorrectly 
formatted. 

TEXT TRUNCATED No BASIC-PLUS statement can be more 


than 255 characters long. 


TOO FEW ARGUMENTS The function has been called with 
a number of arguments not equal to 
the number defined for the function. 


TOO MANY ARGUMENTS A user-defined function may have up 
to five arguments. 


UNDEFINED FUNCTION CALLED BASIC-PLUS interpreted some state- 
ment component as a function call 
for which there is no defined func- 
tion (system or user). 


WHAT? Command or immediate mode statement 
entered to BASIC-PLUS could not be 
processed. Illegal verb or improper 
format error most likely. 


WRONG MATH PACKAGE Program was compiled with an incom- 


patible version of RSTS. Program 
source must be recompiled. 


C.3 SYSTEM IDENTIFICATION MESSAGE 


ERR code 9 is associated with the system installation name 


for use by the system programs. 


APPENDIX D 


BASIC-PLUS CHARACTER SET 


D.1 BASIC-PLUS CHARACTER SET 


User program statements are composed of individual characters. 


Allowable characters come from the following character set: 


A through 2 
@ through 9 
Space 

Tab 


and the following special symbols and keys: 


Key Use and Section in BASIC-PLUS Language Manual 
$ Used in specifying string variables (Section 5.1), or 


as the System Library file designator (RSTS-11 System 
User's Guide). ; 


% Used in specifying integer variables (Section 6.1). 
Also denotes account [1,4] (Section 9.1.1). 


ae Used to delimit string constants, i.e., text strings 
(Section 5.1). 


Begins comment part of a line (Section 3.1). Also 
denotes account [1,3] (Section 9.1.1). 


: Separates multiple statements on one line (Section 
2.3.1). 


a8 Separates multiple statements on one line as the colon 
(:) also does. 


# Denotes a device or file channel number, or is used as 
an output format effector (Chapter 7 and Section 10.3.3). 
Also denotes account number using current project num- 
ber with a programmer number of § (Section 9.1.1). 


Output format effector and list terminator 
(Section 3.3). 


; Output format effector (Section 3.3). 


& Denotes account [1,5] (Section 9.1.1). 
@ Denotes the assignable account (Section 9.1.1). 
LINE When used at the end of a line, indicates that the cur- 
FEED rent statement is continued on the next line 
(Section 2.3.2). 
(.) Used to group arguments in an arithmetic expression 
(Section 2.5), or to delimit project-programmer number. 
{] Used to group project-programmer number. Equivalent 
to (). 


Use and Section in BASIC-PLUS Language Manual 


Used to delimit file protection codes. 
Arithmetic operators (Section 2.5.3). 


Replacement operator (Section 3.2). Logical equivalence 
operator (Section 2.5.4). 


Logical "less than" operator (Section 2.5.4). 
Logical "greater than" operator (Section 2.5.4). 


Numeric “approximately equal to" operator (Section 2.5.4). 
Logical "exactly equal to" string operator 
(Section 5.1.5). 


D.2 ASCII CHARACTER CODES 


ASCII ASCII ASCII 
Char- RSTS Decimal Char- RSTS Decimal Char- RSTS 


acter Usage Value acter Usage Value acter Usage 


@ NUL FILL character Vv 
1 SOH W 
2 sTX - x 
3 ETX CTRL/C 46 ‘ 89 Y 
4 EOT 47 / og Z 
5 ENQ 48 g 91 [ 
6 ACK 49 1 92 \. Backslash 
7 BEL BELL 52 2 93 ] 
8 BS 51 3 94 “or + 
9 HT HORIZONTAL TAB 52 4 95 ior + 
1g LF LINE FEED 53 5 96 ~ Grave accent 
11 VT VERTICAL TAB 54 6 97 a 
12 FF FORM FEED 55 7 98 b 
13 CR CARRIAGE RETURN 56 8 99 c 
14 so 57 9 198 d 
15 SI CTRL/O 58 : 1f1 e 
16 DLE 59 ; 1g2 f 
17 DCcl 6g < 193 g 
18 DC2 61 = 194 h 
19 DC3 62 > 195 i 
2g Dc4 63 ? 196 5 
21 NAK CTRL/U 64 @ 197 k 
22 SYN 65 A 198 1 
23 ETB 66 B 1g9 m 
24 CAN 67 c 11g n 
25 EM 68 D 111 ° 
26 SUB CTRL/Z 69 E 112 p 
27 ESC ESCAPE! 1B F 113 q 
28 FS 71 G 114 x 
29 GS 72 H 115 s 
36 RS 73 I 116 t 
31 US 74 J 117 u 
32 SP SPACE 75 K 118 v 
33 ! 76 L 119 w 
34 7 77 M 12g x 
35 # 78 N 121 y 
36 $ 79 re) 122 Zz 
37 % 8¢ P 123 { 
38 & gl Q 124 | Vertical Line 
39 '  APOSTROPHE 82 R 125 
46 ( 83 s 126 ~ Tilde 
41 ) 84 T 127 DEL RUBOUT 
42 * 85 U 


1ALTMODE (ASCII 125) or PREFIX (ASCII 126) keys which appear on some terminals are 


translated internally into ESCAPE. 


Radix-59 Character/Position Table 


Single Char. 
or Second Third 
First Char. Character Character 


A 083169 A G29959 A GBASG1 
B 666266 B 666126 B CHOC L2 
Cc 611366 c 666176 Cc $6666 3 
D 614466 D 666246 D O66604 
E 617568 E 666316 E 666665 
F 622666 F 666366 F 666666 
G 625768 G 666436 G 6660667 
H 631666 H 606566 H 662816 
I 634166 I 666556 I 666611 
J 637266 J 666626 J 666612 
K 642366 K 666676 K 666613 
L 645468 L 666746 i 666614 
M 650568 M 661616 M 666615 
N 653688 N 661666 N 666816 
e) £56766 oO 0611328 ) G66017 
P 062686 P 661266 P 666620 
Q 665166 Q 661258 Q 666821 
R 076266 R 661328 R OO6G22 
s 073328 Ss 661376 Ss £66623 
T 076466 T £61446 T $86624 
U 161588 U £61518 U 686625 
V 164688 Vv 601568 V $66626 
Ww 167766 Ww 661638 W 666627 
X 1136868 x 021708 X £660 36 
Y 116182 Y 001752 Y PEP631 
Zz 121268 Zz O62626 Zz 666032 
$ 124368 $ £22676 $ 069833 
A 127468 . $6214¢ ; 660634 
unused 132599 unused #6221¢ unused £9635 
g 135688 g 662268 6 
1 1497828 1 002336 
2 144668 2 662468 2 C0006 40 
3 14716¢ 3 662458 3 OOS 41 
4 152268 4 062528 4 S6EG42 
5 155388 5 662576 5 £GGB43 
6 1604089 6 662648 6 COGS 44 
7 163588 7 022716 7 OP0B45 
8 166668 8 062768 8 £06S46 
9 171760 9 003038 9 O00G47 


APPENDIX E 


RSTS FLOATING-POINT AND INTEGER FORMATS 


E.1 FLOATING-POINT FORMATS 


RSTS systems use two standard floating-point packages: the 
Single precision, two-word package or the double precision, four-word 
package. The determination of which 


HO 


ackage will be used is made by 


thea + + the +2 
bie SyYOSeeil ttawmayer ab LIlIe LI 


The single precision format provides economical storage, while 
the double precision format is used for high accuracy. The single 


precision format provides up to 24 bits or approximately seven decimal 


we P . -38 
digits of accuracy. The magnitude range lies between 9.29 x 19 


and 1.7 x 1p?8, Double precision calculations have a precision of 56 
bits or approximately sixteen decimal digits, with magnitudes in the 


same range as for single precision format. 


15 14 7 6 0 


SINGLE PRECISION FORMAT (2 WORD) 


wordt6: lowest-order mantissa 


DOUBLE PRECISION FORMAT (4 WORD) 


The exponent is stored in excess 128 (226.4) notation. Exponents 
from -127 to +127 are represented by the binary equivalent of 1 through 
255 (1 through 3779). Fractions are represented in sign magnitude no- 
tation with the binary radix point to the left. Numbers are assumed to 
be normalized and, therefore, the most significant bit is not stored 
because it is redundant (this is called "hidden bit normalization"); it 
is always a 1 unless the exponent is @ in which case it is assumed to 
be @. The value 9 is therefore represented by two or four words of 


zeroes. For example: +1 would be represented by: 


word: GAG 299 
word+2: GLCSLH 


in the 2-word format, or: 


word: G49299 
word+2: PPSISL 
wordt+4: LLLLGB 
word+6: GASEEL 
in the 4-word format. -5 would be: 
word: 149649 
word+2: GIIGOS 
in the 2-word format, or: 
word: 1496 4p 
word+2: GLIIAS 
wordt+4: CLASS 
wordt+é: PIGBOS 


in the 4-word format. 


While it is generally possible to run programs written on one 
RSTS system on another RSTS system, certain restrictions apply if the 


math packages are not the same. These are: 
a. Programs depending on 4-word accuracy cannot be run 
with the 2-word package. 


b. .BAC compiled programs can not be interchanged. 
The program source file must be recompiled. 


c. Floating-point virtual core array file formats are 
not compatible between math packages. 


d. Programs using the RECORD I/O functions CVTSF and 
CVTFS are not compatible between math packages. 


E.2 INTEGER FORMAT 


15 14 g 


Integers are stored in a two's complement representation. Integer 


values must be in the range -32768 to +32767. For example: 


+22 
-7 


9900264 
177771. 


As a rule, an integer value is assumed by RSTS only where a con- 
stant or variable name is followed by a % character. Otherwise, con- 


stants and variables are assumed to be floating-point values. 
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ABS function, 3-23 Brackets, 

Account, 9-3, 9-4, 9-7 angle (<>), 1-3, 2-8, 2-9 
assignable, 9-4 square ([]), 1-3 
auxiliary library, 9-6 Buffer size, device, 9-10 
number, 9-3 card reader, 9-10 

Alphabetic sequence string, 5-4 DECtape, 9-10 

ALT mode, 3-9 disk, 9-10 

AND operator, 2-9, 3-14 high-speed punch, 9-10 


Angle brackets (<>), 1-3, 2-8 


, 2-9 high-speed reader, 9-10 
Arithmetical hierarchy, 2-7, 2-8 


line printer, 9-10 


Arithmetic expressions, 2-5 magtape, 9-10 
Arithmetic, mixed mode, 6-9 user terminal, 9-10 
Arithmetic operators, 2-7 BUFSIZ function, 12-6 


with matrices, 7-6 
Arithmetic, scaled, 6-10 


Array, 7-l 
storage, 11-7, 11-15, 11-16 Calculations, 
variables, 3-19, 3-20 immediate mode, 4-1 
virtual, 11-1, 11-20 matrix, 7-6 
Array variables, 3-19, 3-20 Card reader, buffer size, 9-10 
character string, 5-3 CHAIN statement, 9-19, 9-20 
default values, 3-21 CHANGE statement, 5-5 
virtual core, 11-4 Channel numbers, 9-7 
zero elements, 3-21, 7-5, 7-7 FIELD, 12-9 
see also matrix virtual array, 11-2, 11-4 
ASCII, Character code, ASCII, 5-6, D-3 
character code, 5-6, D-3 Characters, 
conversions, 5-5 RADIX-50 set, D-4 
formatted I/O, 10-5 special, 9-6 
function, 5-13 Character string, 5-1 
table, 5-2, D-3 alphabetic sequence, 5-4 
Assignable account, 9-4 ASCII conversion, 5-5 
Assignable devices, 9-2, 9-9 constants, 5-2 
Asterisk (*), 10-9 field, 10-7 
** operator, 2-7 functions, 5-11, 5-13, 5-14, 
ATN function, 3-23 5-15 
Auxiliary library account, 9-6 generating (STRINGS), 5-15 
input, 5-8 
output, 3-7, 5-10, 5-11 
passing (CVTS$), 5-15, 12-17, 12~18 
-BAC extension, 9-3 relational operators, 5-4 
Backslash (\), 2-3, 10-8 size, 5-4 
-BAS extension, 9~3 user-defined, 8-3 
BASIC PLUS variables, 5-3, 5-4 
command summary, B-1l virtual core arrays, 11-3 
language, 1-4 CHRS function, 5-6, 5-13 
language summary, A-1 CLOSE statement, 9-16 
statements, A-6 Record I/O, 12-2 
Block, virtual array files, 11-4 
data, 3-4 CLUSTERSIZE option, 9-12 
disk, 9-12 Codes, protection, 9-4, 9-5 
Boolean algebra, 2-9, 6-4 Comma (,), 3-7, 3-8, 3-9, 7-2, 10-11 


Braces ({} ), 1-3 


INDEX-1 
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Commands, DEF statement, 3-27, 8-1 
BASIC-PLUS, B-l immediate mode, 4-3 
definition, 1-4 multiple line, 8-1 

Comments, DEF FN statement, 3-27 
data, 3-5 Depth of nesting, 3-18 
program, 3-1, 3-2 Device, 

Concatenate, strings, 5-13 assignable, 9-2, 9-19 

Conditional FOR loops, 2-8, 8-16 buffer sizes, 9-10 

Conditional transfer, 3-12 designation, 9-2 

Conditions, 3-13 designator, 9-1 
see also relational operators file structured, 9-15 

and logical operators non-file structured, 9-15 

Conformable matrix, 7-6 Dimensioning,3-21, 11-2 

CON function, 7-5 implicit, 7-1 

Constants, DIM statement, 3-20, 3-22, 5-3 
ambiguous, 6-10, 6-11 immediate mode, 4-3 
character string, 5-2 virtual core, 11-2 
floating point, 6-10 DIM# statement, 11-2 
integer, 6-l Disk, 
numeric, 2-5 appending data, 10-22 

CONT command, 4-1, 4-2 blocks, 9-12 

Control, buffer size, 9-10 
character, special, B-3 private, 9-6, 9-7 
variable, 3-17, 3-19 public, 9-6, 9-7 

Conventions, documentation, 1-3 STATUS value, 12-6, 12-7 

Conversion functions, CVT, 12-16 - update option, 12-14, 12-15 

12-21 virtual core, 11-11 

cos function, 3-23 Documentation conventions, 1-3 

COUNT option, 12-5 Dollar sign ($) character, 9-4, 

CTRL/C command, 4-2 10-11 

CTRL/Z command, 10-16 Double precision, 6-10 

CVT conversion functions, 12-16 Dummy variables, 2-38, 8-1 


CVTS$, 12-17, 12-18 


E format numbers, 2-6 


Data block, 3-4 END statement, 3-34 

Data, EQV operator, 2-10, 3-14 
appending, 10-22 ERL variable, 8-13 
files, 9-1 Error messages summary, C-l 
storage, 9-1 Errors, 

Data files, 9-1 disabling error control, 8-12 
formatted ASCII, 10-5 ERL variable, 8-13 
input/output, 9-1 nonrecoverable, C-6 
random access, 11-1 ON ERROR GOTO statement, 8-5 
Record I/O, 12-1 program control of, 8-5 
see also virtual array files user recoverable, 8-6, C-l 

DATA statement, 3-2, 3-4, 10-1 ERR variable, 8-6 
character strings, 5-8, 5-9,10-1 values, 8-6, 8-9 
comments, 3-5, 10-1 ESCAPE key, 3-9 
data pool storage, 10-1 Equivalent, logically, 2-10 
immediate mode, 4-3 Exclamation point (!), 3-1, 10-7 
simplest form, 3-4 Exclusive OR operator, 2-9 

DATES function, 5-13, 8-24 EXP function, 3-23 

Debugging, 4-l, 4-2 Exponential format, 10-10 

Decimal notation, 2-5 Expressions, 2-5 

DECtape, buffer size, 9-10 arithmetic, 2-5 


logical, 2-5 
relational, 2-9 


INDEX-2 


INDEX (Cont.) 


Extending disk files, 12-8 
Extension, 9-3 

-BAC, 9-3 

-BAS, 9-3 

format, 9-2 

reserved file, 9-3 

-TMP, 9-3 


FALSE logical value, 6-4, 6-5 
Field, 
insufficient, 10-12 
numeric, 10-8 
string, 10-8 
too large, 10-12 
FIELD statement, 12-9 
File extensions, reserved, 9-3 
Filename, 
format, 9-2 
renaming, 9-17 
specification, 9-1 
Files, data, 9-1 
formatted ASCII, 10-5 
random access, 11-1 
Record I/O, 12-1 
see also virtual array files 
Files, DECtape, 9-2 
Files, disk, 
extending, 12-8 
locked, 12-15 
(proj,prog], 9-3 


simultaneous multiple users, 12-14 


UNLOCK, 12-15 

update mode, 12-14 

virtual core arrays, 11-4 
FILESIZE option, 9-14 
File-structured device, 9-2 
FIX function, 3-23 


Floating-point number, 2-5, 6-l, 


6-10 
FNEND statement, 8-1 
immediate mode, 4-3 
Format, 
E, 2-6 
exponential, 10-10 
insufficient, 10-12 
too large, 10-12 


Formatted ASCII data files, 10-5 


FOR modifier, 8-20 

FOR statement, 3-16 
conditional loops, 2-8 
conditional termination, 8-16 
immediate mode, 4-3 
nesting loops, 3-18 
test condition, 3-16 


Function, definition, multiple-line, 


Function, A-2 
conversion, 12-16 
mathematical, 3-23 
matrix, 7-5, 7-7 
PRINT, 10-15 
recursive, 8-2 
string, 5-11, 5-13 
system, 8-24 


user-defined, 3-27, 5-1ll, 6-4, 


8-1 


Functions, conversion, 12-16 


CVT%$, 12-16 

CVTS%, 12-16 

CVTFS$, 12-16 

CVTSF, 12-16 

CVTSS, 12-16 
Functions, mathematical, 

ABS, 3-23 

ATN, 3-23 

COS, 3-23 

EXP, 3-23 

FIX, 3-23 

INT, 3-23, 3-24 

LOG, 3-23 

LOG10, 3-23 

PI, 3-23 

RND, 3-23, 3-25 

SGN, 3-23 

SIN, 3-23 

SOR, 3-23 

TAN, 3-23 
Functions, PRINT, 10-15 

POS, 10-15 

TAB, 10-15 


Functions, string, 5-11, 


ASCII, 5-13 
CHRS, 5-13 
DATES, 5-13 
INSTR, 5-14 
LEFT, 5-13 
LEN, 5-13 
MID, 5-13 
NUMS, 5-14 
+, 5-13 
RIGHT, 5-13 
SPACES, 5-14 
STRINGS, 5-15 
TIMES, 5-14 
VAL, 5-14 
XLATE, 12-24 
Functions, system, 
DATES (9), 8-24 
DATES, 8-24 
RADS, 8-25 
SWAP%, 8-25 
TIMES, 8-24 
TIMES (8), 8-24 
TIME(S), 8-24 
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3-23 


5-13 
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Functions, 
TIME(1), 
TIME(2), 
TIME(3), 
TIME (4), 


system, 
8-24 
8-24 
8-25 
8-24 


(Cont.) 


General hierarchy, 3-14 
Generating strings (STRINGS), 
5-15 
GET statement, 
GOSUB statement, 3-33 
immediate mode, 4-3 
GOTO statement, 3-11 
conditional branch, 
immediate mode, 4-3 
unconditional branch, 


12-2 


3-12 


3-11 


Hierarchy, 
arithmetical, 
general, 3-14 
see also priority 


2-7, 2-8 


IDN function, 7-5 
IF clause, 2-8 
IF-GOTO statement, 3-12, 
IF modifier, 8-19 
IF-THEN statement, 
3-15, 8-14 
IF-THEN-ELSE statement, 
Immediate mode, 4-1 
multiple statements, 
restrictions, 4-3 
Implication, logical, 2-10 
Implicit dimensions, 7-1 
IMP operator, 2-10, 3-14 
Increments, 2-1 
Input, 
character strings, 
integers, 6-2 
matrices, 7-2, 7-3 
INPUT LINE statement, 
message output, 5-10 
Input/output operations, 
Input/output, 
data files, 
program, 3-3 
INPUT statement, 
character string input, 5-9 
from data files, 10-16 
from non-terminal devices, 
message output, 3-11 
simplest form, 3-9 


3-15 
2-8, 3-12, 
8-14 


4-2 


5-8 


5-9, 10 
10-1 


9-1 


-18 


10-19 


INSTR function, 5-14 

Integer numbers, 6-1 
arithmetic, 6-1, 6-2 
constants, 6-1 


functions, user-defined, 6-4 
I/O, 6-3 
numbers, 6-1L 
user-defined functions, 
variables, 6-1 

Internal file designators, 
FIELD, 12-9 


8-3 


user terminal, 9-7 
virtual array, 11-2 
INT function, 3-23, 3-24 


Inversion of matrices, 7-7 
I/O program, 3-3 
complete discussion, Part III 


Italic type, 1-3 


Key, 
ALT mode, 3-9 
escape, 3-9 
LINE FEED, 
RETURN, 2-3 
KILL statement, 


2-3 


9-18 


Language summary, BASIC-PLUS, A-l 
LEFT function, 5-13 
LEN function, 5-13 
LET statement, 3-2, 
Library, 
auxiliary, 9-6 
system, 9-3, 9-6 
Line, 1-4 
multiple statements on single, 
2-3 
single statement on multiple, 
2-3 
terminators, 
LINE variable, 
LINE FEED key, 
Line numbers, 
range, 2-1 
Locked file, 
LOG function, 
LOG10 function, 
Logical, 
expressions, 
implication, 
negative, 2-9 
operations, 6-5 
operators, 2-9, 
product, 2-9 
sum, 2-9 
value, 2-9, 
variables, 


3-3, 12-13 


5-10 
4-3 
2-3 
1-3, 2-1 
12-14 
3-23 
3-23 


2-5, 
2-10 


2-9, 2-10, 3-13 


6-4 


6-4 
6-4 


INDEX-4 


INDEX 


Logically equivalent, 2-10 
Loops, program, 3-13, 3-15 
conditional termination of, 
8-16 
nested, 3-18 


LSET statement, 12-12, 12-13 


Mathematical functions, 


2-972 
g7425 


3-22, 


see also functions, mathematical 


Mathematical operators, 2-7 

MAT INPUT statement, 7-3, 10-19 

MAT PRINT statement, 7-2, 10-14 

MAT READ statement, 7-2, 10-2 

Matrix, 3-21, 7-1, 10-2 
calculations, 7-6 
conformable, 7-6 
functions, 7-7 
initialization statement, 
inverting, 7-7 
MAT INPUT, 7-3, 
MAT PRINT, 7-2, 
MAT READ, 7-2, 
multiplication, 
multiplication, 
operations, 7-6 
square, 7-7 
string variables, 
virtual core, 11-1 

Memory, conserving, 3-22 

Messages, program, 3-2 
by INPUT, 3-11 
by PRINT, 3-8 

MID function, 5-13 

Minus sign (-), trailing, 10-10 

Mixed mode arithmetic, 6-9 

MODE specification, 9-15 
MODE 1%, 12-14 
MODE 2%, 10-22 

Modifiers, 8-19 

Modules, arithmetic example, 3-29 

Multiple lines, 2-3 
function, definition, 
immediate mode, 4-2 

Multiple statements, 
modifiers, 8-23 

Multiple terminal service, 


7-5 


10-19 

10-14 
10-2 

7-6 


scalar, 7-6 


5-2 


8-1 
2-3 


11-16 


NAME-AS statement, 9-17 

Negative, logical, 2-9 

Nesting, 
functions, 
loops, 3-18 
subroutines, 


8-1 


3-34 
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NEXT statement, 3-16, 
immediate mode, 4-3 
Non-file structured devices, 9-2 
RECOUNT variable, 12-4 
Non-recoverable errors, C-6 
Notation, 
decimal, 2-5 
scientific, 
NOT operator, 2-9, 
Null string, 5-3 
NUMS function, 5-14 
Number, 2-5 
E format, 2-6 
floating point, 2-5, 
integer, 6-1 
output format, 3-6 
Number sign (#), 10-8 
Numeric constants, 2-5 
Numeric field, 10-8 


3-17 


2-6 
3-14 


6-1, 6-10 


OLD command, 3-34 


ON ERROR GOTO statement, 8-5 


disabling error routine, 8-12 
ON ERROR GOTO @, 8-12 
RESUME, 8~9 
ON-GOSUB statement, 8-4 
ON-GOTO statement, 8-3 
Open, 
multiple terminals, 11-16 
statement, 9-7, 11-4, 12-1 
OPEN statement, 9-7, 11-4, 12-1 
CLUSTERSIZE option, 9-12 
FOR INPUT, 9-8 
FOR OUTPUT, 9-8 
MODE option, 9-15 
Record I/O, 12-1 
RECORDSIZE option, 9-10 


user terminal, 10-21 

virtual array file, 11-4 
Operations, 

input/output, 10-1 

Matrix, 7-6 
Operators, logical, 2-9, A-l 

AND, 2-9 

ek, 2-7 

EQV, 2-10 

IMP, 2-10 

NOT, 2-9 

OR, exclusive, 

XOR, 2-9 
Operators, mathematical, 
Operators, relational, 2- 

string, 5-4 
OR operator, 


2-9 


2-7 
8 


2-9, 3-14 
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Output, 
character strings, 
integers, 6-2 
Matrices, 7-2 
rules for PRINT statement, 
10-3 
see also PRINT 


5-11 


Pack cluster size, 9-12 
Parentheses, 2-8 
Passing strings (CVTS$), 12-17 
Percent character (%),6-1, 10-12 
Physical blocks, 9-12 
PI function, 3-23 
POS function, 10-15 
Pound sign (#), 10-8 
Precedence rules, 
see priority 
Print functions, 10-15 
PRINT statement, 3-6, 10-3 
character string format, 3-8 
10-7 
comma, 10-11 
message output, 3-8 
number format, 3-6 
output rules, 10-3 
performing calculations, 3-6 
punctuation, 10-4 
semicolon, 10-4 
simplest form, 3-6 
suppress carriage return/line 
feed, 3-9 
to data files, 10-5 
to non-terminal devices, 
without arguments, 3-6 
PRINT-USING statement, 10~7 
punctuation, 10-13 
Print zones, 3-7 
Priority, 
general, 3-14 
mathematical, 2-7, 2-8 
Private disk, 9-6 
Product, logical, 2-9 
Programs, 1-4 
conserving memory space, 
debugging, 4-1, 4-2 
line, 1-4 
loops, 3-15 
Project-programmer codes, 
9-3 
Protection code, 9-1, 9-4 
assigning, 9-17 
Public disk, 9-6 
Punctuation, PRINT statement, 
10-13 
PUT statement, 


10-6 


3-22 


9-1, 


12-2 


Question mark (?), printed by INPUT, 
3-11 
Quotation mark ("), 3-8 


RAD$ function, 8-25 
RADIX-50 character set, D-4 
Random access file system, 11-1 
see also virtual array files 
RANDOMIZE statement, 3-26 
RANDOM statement, 3-26 
Random number function, RND, 
READ statement, 3-4, 10-1 
Record I/O options, 12-1 
CLOSE, 12-2 
examples, 12-22 
FIELD, 12-9 
LSET, 12-12 
RSET, 12-12 
translation function, 
update, 12-14 
RECORD option, 12-5 
multiple terminals, 11-6 
RECORDSIZE option, 9-10 
RECOUNT variable, 12-4 
Relational, 
expressions, 2-9, 2-10, 8-14, 8-20 
through 8-23 
operators, 2-8 
operators with character strings, 
5-4 
Remarks, program, 3-2 
REMARK statement, 3-1 
REM statement, 3-1 
Renaming filename, 9-17 
Reserved file extensions, 9-3 
RESTORE statement, 3-5, 10-2 
RESUME statement, 8-10 
RETURN key, 2-3 
RETURN statement, 3-33, 8-4 
immediate mode, 4-3 
RIGHT function, 5-13 
RND function, 3-23, 3-25 
Routine, error handling, 8-11 
RSET statement, 12-12 
RSTS-11 System User's Guide, 1-1 


3-25 


12-24 


SAVE command, 3-34 

Scalar multiplication, 7-6 
SCALE command, 6-11 
Scaled arithmetic, 
Scale factor, 6-12 
Scientific notation, 2-6 
Semicolon, 3-8, 3-9, 7-2 
SGN function, 3-23 


6-10 
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Simple variables, 3-19 Time-sharing system, 1-2 


SIN function, 3-23 TIMES function, 5-14, 8-24 
Single precision, 6-10 -TMP extension, 9-3 
Single statement on multiple Trailing minus sign, 10-10 
lines, 2-3 Transfer, program 
Size, string, 5-4 conditional, 3-12 
SLEEP statement, 8-25 unconditional, 3-11 
SPACE function, 5-14 Transposition, matrix, 7-7 
Spaces, 2-4 TRUE logical value, 6-4, 6-5 
Special characters, Truth table, 2-10, 6-6 
t, 9-6 
%, 6-1, 9-6, 10-12 UFD (User File Directory), 9-12 
&, 9-6 Unary operators, 
#, 9-6, 10-10 minus, 2-7 
$, 9-6, 10-11 plus, 2-7 
Special control characters, B-4 Unconditional program transfer, 3-11 
SQR square root function, 3-23 UNLESS statement modifier, 2-8, 8-20 
Square brackets, 1-3 UNLOCK statement, 12-14 
Square matrix, 7-7 UNTIL statement modifier, 2-8, 8-16, 
Statement modifiers, 8-19 8-20 
FOR, 8-19 Up-arrow (+t) symbol, 2-7, 10-10 
IF, 8-19 Update option, 12-14 
Multiple, 8-23 User-defined functions, 3-27, 4-3 
UNLESS, 8-19 function names, 3-27 
UNTIL, 8-16, 8-19 immediate mode, 4-3 
WHILE, 8-16, 8-19 integer, 6-4 
Statements, 1-4, 2-3 multiple line, 8-1 
definition of, 1-4 string, 5-11 
multiple on single line, 2-3 User File Directory (UFD), 9-12 
single on multiple lines, 2-3 User's Guide, RSTS-11 System, 1-1 
summary of, A-5 User-recoverable, errors, 8-6, C-l 


see also specific statement names 
Status variable, 12-6 
STEP expression, 3-17, 8-16 


STOP statement, 3-34, 4-1 VAL function, 5-14 
Storage, virtual array, 11-3 Value, matrix function, 
String, CON, 7-5 
see character string IDN, 7-5 
STRINGS function, 5-15 ZER, 7-5 
Subroutine, 3-32 Variables, 2-6 
GOSUB, 3-32 character string, 5-2 
nesting, 3-34 dummy, 3-28, 8-1 
ON-GOSUB, 8-4 ERL, 8-12 
Subscripted variables, 3-19 ERR, 8-6 
default values, 3-21 floating point, 2-6 
string variables, 5-3 integer, 6-1 
zero elements, 3-21 LINE, 4-3 
Sum, logical, 2-9 logical, 6-4 
SWAPS function, 8-24 numeric, 2-6 
Symbols, relational, 2-8 RECOUNT, 12-4 
Syntax, 2-1 simple, 3-19 
System functions, 8-23, 8-24 STATUS, 12-6 
System library account, 9-3, 9-6 subscripted, 3-19, 3-20, 5-3, 7-1 
types, A-1l 
Virtual array files, 11-1 
TAB function, 10-15 example, 11-17 
Tabs, 2-4 opening, 11-4 
TAN function, 3-23 string storage, 11-3 


Terminal input, 
see INPUT statement and INPUT 
LINE statement 
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Virtual core, 11-1 
data storage, 11-7 
DIM statement, 11-2 
opening file, 11-4 
string storage, 11-3 


WAIT statement, 8-25 
WHILE statement modifier, 2-8, 
8-16, 8-20 


XLATE function, 12-24 
XOR operator, 2-9, 3-14 


ZER function, 7-5 
Zones, print, 3-7 
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Did you find errors in this manual? If so, specify by page. 


Did you find this manual understandable, usable, and well-organized? 
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6 
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3 Is there sufficient documentation on associated system programs 

7 required for use of the software described in this manual? If not, 
3 what material is missing and where should it be placed? 

oe 
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Higher~level language programmer 
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Cj 
CJ 
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